@nativesquare/soma 0.10.2 → 0.12.0

package/src/component/garmin/public.ts

@@ -1,1406 +1,1049 @@
-// ─── Garmin Public Actions ───────────────────────────────────────────────────
-// Public actions that handle the full Garmin OAuth 2.0 PKCE + sync lifecycle.
-// The host app calls these through the Soma class, which threads the
-// credentials automatically from env vars or constructor config.
-
-import { v } from "convex/values";
-import { action } from "../_generated/server";
-import type { Doc, Id } from "../_generated/dataModel";
-import { generateState } from "../utils.js";
-import {
-  generateCodeVerifier,
-  generateCodeChallenge,
-  buildAuthUrl,
-  exchangeCode,
-  refreshToken,
-} from "./auth.js";
-import {
-  createWellnessClient,
-  createTrainingClient,
-} from "./client.js";
-import { buildTimeRangeQuery, timeRangeQuery } from "./utils.js";
-import {
-  createWorkoutV2 as sdkCreateWorkoutV2,
-  createWorkoutSchedule as sdkCreateWorkoutSchedule,
-} from "./types/trainingApiWorkouts/sdk.gen";
-import {
-  userId as sdkUserId,
-  dereg as sdkDereg,
-  getActivities,
-  getDailies,
-  getSleeps,
-  getBodyComps,
-  getMct,
-  getBloodPressures,
-  getSkinTemp,
-  getUserMetrics,
-  getHrv,
-  getStressDetails,
-  getPulseox,
-  getRespiration,
-} from "./types/wellnessApi/sdk.gen";
-import { transformActivity } from "./transform/activity.js";
-import { transformDailies } from "./transform/dailies.js";
-import { transformSleeps } from "./transform/sleeps.js";
-import { transformBodyComposition } from "./transform/bodyCompositions.js";
-import { transformMenstrualCycleTracking } from "./transform/menstrualCycleTracking.js";
-import { transformBloodPressure } from "./transform/bloodPressure.js";
-import { transformSkinTemperature } from "./transform/skinTemperature.js";
-import { transformUserMetrics } from "./transform/userMetrics.js";
-import { transformHRVSummary } from "./transform/hrvSummary.js";
-import { transformStress } from "./transform/stress.js";
-import { transformPulseOx } from "./transform/pulseOx.js";
-import { transformRespiration } from "./transform/respiration.js";
-import { transformPlannedWorkoutToGarmin } from "./transform/plannedWorkout.js";
-import { api, internal } from "../_generated/api";
-
-// Default sync window: last 30 days
-const DEFAULT_SYNC_DAYS = 30;
-
-// Refresh buffer: refresh tokens 10 minutes before expiry
-const REFRESH_BUFFER_SECONDS = 600;
-
-// ─── OAuth ──────────────────────────────────────────────────────────────────
-
-/**
- * Generate a Garmin OAuth 2.0 authorization URL with PKCE.
- *
- * The PKCE code verifier and state are stored in the component's
- * `pendingOAuth` table so that `completeGarminOAuth` can look them up
- * automatically when the callback fires via `registerRoutes`.
- */
-export const getGarminAuthUrl = action({
-  args: {
-    clientId: v.string(),
-    redirectUri: v.optional(v.string()),
-    userId: v.string(),
-  },
-  handler: async (ctx, args) => {
-    const codeVerifier = generateCodeVerifier();
-    const codeChallenge = await generateCodeChallenge(codeVerifier);
-    const state = generateState();
-
-    const authUrl = buildAuthUrl({
-      clientId: args.clientId,
-      codeChallenge,
-      redirectUri: args.redirectUri,
-      state,
-    });
-
-    await ctx.runMutation(internal.garmin.private.storePendingOAuth, {
-      provider: "GARMIN",
-      state,
-      codeVerifier,
-      userId: args.userId,
-    });
-
-    return { authUrl, state, codeVerifier };
-  },
-});
-
-/**
- * Complete a Garmin OAuth 2.0 flow using stored pending state.
- *
- * Called internally by `registerRoutes` — the callback handler calls
- * this with the `code` and `state` from the redirect. The action looks
- * up the pending state (codeVerifier, userId) stored during
- * `getGarminAuthUrl`, exchanges for tokens, creates the connection,
- * stores tokens, and cleans up the pending entry.
- *
- * The host app is responsible for calling `syncGarmin` afterwards.
- */
-export const completeGarminOAuth = action({
-  args: {
-    code: v.string(),
-    state: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    redirectUri: v.optional(v.string()),
-  },
-  handler: async (ctx, args): Promise<{
-    connectionId: Id<"connections">;
-    userId: string;
-  }> => {
-    const pending: Doc<"pendingOAuth"> | null = await ctx.runQuery(internal.garmin.private.getPendingOAuth, {
-      state: args.state,
-    });
-    if (!pending) {
-      throw new Error(
-        "No pending Garmin OAuth state found for this state parameter. " +
-        "The authorization may have expired or was already used.",
-      );
-    }
-
-    if (!pending.codeVerifier) {
-      throw new Error(
-        "No code verifier found for this state parameter. " +
-        "The authorization may have expired or was already used.",
-      );
-    }
-
-    const tokenResult = await exchangeCode({
-      clientId: args.clientId,
-      clientSecret: args.clientSecret,
-      code: args.code,
-      codeVerifier: pending.codeVerifier,
-      redirectUri: args.redirectUri,
-    });
-
-    const _deleted: null = await ctx.runMutation(internal.garmin.private.deletePendingOAuth, {
-      state: args.state,
-    });
-
-    const connectionId: Id<"connections"> = await ctx.runMutation(api.public.connect, {
-      userId: pending.userId,
-      provider: "GARMIN",
-    });
-
-    const expiresAt = Math.floor(Date.now() / 1000) + tokenResult.expires_in;
-    const _stored: null = await ctx.runMutation(internal.garmin.private.storeTokens, {
-      connectionId,
-      accessToken: tokenResult.access_token,
-      refreshToken: tokenResult.refresh_token,
-      expiresAt,
-    });
-
-    // Best-effort: resolve Garmin user ID for webhook mapping
-    const wellnessClient = createWellnessClient(tokenResult.access_token);
-    const { data: userIdData } = await sdkUserId({ client: wellnessClient });
-    const garminUserId = userIdData?.userId ?? null;
-    if (garminUserId) {
-      const _updated: null = await ctx.runMutation(api.public.updateConnection, {
-        connectionId,
-        providerUserId: garminUserId,
-      });
-    }
-
-    return {
-      connectionId,
-      userId: pending.userId,
-    };
-  },
-});
-
-/**
- * Disconnect a user from Garmin.
- *
- * Deregisters the user via the Garmin API (best-effort), deletes stored
- * tokens, and sets the connection to inactive.
- */
-export const disconnectGarmin = action({
-  args: {
-    userId: v.string(),
-  },
-  handler: async (ctx, args) => {
-    const connection: Doc<"connections"> | null = await ctx.runQuery(
-      internal.private.getConnectionByProvider,
-      { userId: args.userId, provider: "GARMIN" },
-    );
-    if (!connection) {
-      throw new Error(
-        `No Garmin connection found for user "${args.userId}".`,
-      );
-    }
-
-    const connectionId = connection._id;
-
-    // Best-effort: deregister user at Garmin
-    const tokenDoc: Doc<"providerTokens"> | null = await ctx.runQuery(internal.garmin.private.getTokens, {
-      connectionId,
-    });
-    if (tokenDoc) {
-      try {
-        const wellnessClient = createWellnessClient(tokenDoc.accessToken);
-        await sdkDereg({ client: wellnessClient });
-      } catch {
-        // Deregistration is best-effort; proceed with local cleanup
-      }
-    }
-
-    const _deleted: null = await ctx.runMutation(internal.garmin.private.deleteTokens, { connectionId });
-
-    const _disconnected: null = await ctx.runMutation(api.public.disconnect, {
-      userId: args.userId,
-      provider: "GARMIN",
-    });
-
-    return null;
-  },
-});
-
-// ─── Pull ───────────────────────────────────────────────────────────────────
-
-export const pullActivities = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      {
-        userId: args.userId,
-        clientId: args.clientId,
-        clientSecret: args.clientSecret,
-      },
-    );
-
-    const timeRangeQuery = buildTimeRangeQuery(args, accessToken);
-
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { activities: 0 };
-    const errors: Array<{ type: "activity"; id: string; error: string }> = [];
-
-    try {
-      const { data: activities, error } = await getActivities({
-        client: wellnessClient,
-        query: timeRangeQuery,
-      });
-
-      if (error || !activities) {
-        throw new Error(error ? JSON.stringify(error) : "No data");
-      }
-
-      for (const activity of activities) {
-        try {
-          const data = transformActivity(activity);
-          await ctx.runMutation(api.public.ingestActivity, {
-            connectionId,
-            userId: args.userId,
-            ...data,
-          });
-          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),
-      });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, {
-      connectionId,
-      lastDataUpdate: new Date().toISOString(),
-    });
-
-    return { synced, errors };
-  },
-});
-
-export const pullDailies = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { dailies: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: dailies, error } = await getDailies({ client: wellnessClient, query });
-      if (error || !dailies) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const daily of dailies) {
-        try {
-          const data = transformDailies(daily);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
-          synced.dailies++;
-        } catch (err) {
-          errors.push({ type: "daily", id: daily.summaryId ?? daily.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "daily", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullSleep = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { sleep: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: sleeps, error } = await getSleeps({ client: wellnessClient, query });
-      if (error || !sleeps) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const sleep of sleeps) {
-        try {
-          const data = transformSleeps(sleep);
-          await ctx.runMutation(api.public.ingestSleep, { connectionId, userId: args.userId, ...data });
-          synced.sleep++;
-        } catch (err) {
-          errors.push({ type: "sleep", id: sleep.summaryId ?? sleep.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "sleep", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullBody = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { body: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: bodyComps, error } = await getBodyComps({ client: wellnessClient, query });
-      if (error || !bodyComps) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const body of bodyComps) {
-        try {
-          const data = transformBodyComposition(body);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
-          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) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullMenstruation = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { menstruation: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: records, error } = await getMct({ client: wellnessClient, query });
-      if (error || !records) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const record of records) {
-        try {
-          const data = transformMenstrualCycleTracking(record);
-          await ctx.runMutation(api.public.ingestMenstruation, { connectionId, userId: args.userId, ...data });
-          synced.menstruation++;
-        } catch (err) {
-          errors.push({ type: "menstruation", id: record.summaryId ?? record.periodStartDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "menstruation", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullBloodPressures = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { bloodPressures: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: bpRecords, error } = await getBloodPressures({ client: wellnessClient, query });
-      if (error || !bpRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const bp of bpRecords) {
-        try {
-          const data = transformBloodPressure(bp);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
-          synced.bloodPressures++;
-        } catch (err) {
-          errors.push({ type: "bloodPressure", id: bp.summaryId ?? String(bp.measurementTimeInSeconds), error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "bloodPressure", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullSkinTemperature = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { skinTemp: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: skinRecords, error } = await getSkinTemp({ client: wellnessClient, query });
-      if (error || !skinRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const skin of skinRecords) {
-        try {
-          const data = transformSkinTemperature(skin);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
-          synced.skinTemp++;
-        } catch (err) {
-          errors.push({ type: "skinTemp", id: skin.summaryId ?? skin.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "skinTemp", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullUserMetrics = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { userMetrics: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: metricsRecords, error } = await getUserMetrics({ client: wellnessClient, query });
-      if (error || !metricsRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const metrics of metricsRecords) {
-        try {
-          const data = transformUserMetrics(metrics);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
-          synced.userMetrics++;
-        } catch (err) {
-          errors.push({ type: "userMetrics", id: metrics.summaryId ?? metrics.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "userMetrics", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullHRV = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { hrv: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: hrvRecords, error } = await getHrv({ client: wellnessClient, query });
-      if (error || !hrvRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const hrv of hrvRecords) {
-        try {
-          const data = transformHRVSummary(hrv);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
-          synced.hrv++;
-        } catch (err) {
-          errors.push({ type: "hrv", id: hrv.summaryId ?? hrv.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "hrv", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullStressDetails = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { stressDetails: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: stressRecords, error } = await getStressDetails({ client: wellnessClient, query });
-      if (error || !stressRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const stress of stressRecords) {
-        try {
-          const data = transformStress(stress);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
-          synced.stressDetails++;
-        } catch (err) {
-          errors.push({ type: "stressDetails", id: stress.summaryId ?? stress.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "stressDetails", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullPulseOx = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { pulseOx: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: pulseOxRecords, error } = await getPulseox({ client: wellnessClient, query });
-      if (error || !pulseOxRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const po of pulseOxRecords) {
-        try {
-          const data = transformPulseOx(po);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
-          synced.pulseOx++;
-        } catch (err) {
-          errors.push({ type: "pulseOx", id: po.summaryId ?? po.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "pulseOx", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullRespiration = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const { connectionId, accessToken } = await ctx.runAction(
-      internal.garmin.private.resolveConnectionAndAccessToken,
-      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
-    );
-
-    const query = buildTimeRangeQuery(args, accessToken);
-    const wellnessClient = createWellnessClient(accessToken);
-    const synced = { respiration: 0 };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    try {
-      const { data: respRecords, error } = await getRespiration({ client: wellnessClient, query });
-      if (error || !respRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const resp of respRecords) {
-        try {
-          const data = transformRespiration(resp);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
-          synced.respiration++;
-        } catch (err) {
-          errors.push({ type: "respiration", id: resp.summaryId ?? "unknown", error: err instanceof Error ? err.message : String(err) });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "respiration", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
-    return { synced, errors };
-  },
-});
-
-export const pullAll = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args) => {
-    const sharedArgs = {
-      userId: args.userId,
-      clientId: args.clientId,
-      clientSecret: args.clientSecret,
-      startTimeInSeconds: args.startTimeInSeconds,
-      endTimeInSeconds: args.endTimeInSeconds,
-    };
-    const pullFns = [
-      { ref: api.garmin.public.pullActivities, name: "activities" },
-      { ref: api.garmin.public.pullDailies, name: "dailies" },
-      { ref: api.garmin.public.pullSleep, name: "sleep" },
-      { ref: api.garmin.public.pullBody, name: "body" },
-      { ref: api.garmin.public.pullMenstruation, name: "menstruation" },
-      { ref: api.garmin.public.pullBloodPressures, name: "bloodPressures" },
-      { ref: api.garmin.public.pullSkinTemperature, name: "skinTemp" },
-      { ref: api.garmin.public.pullUserMetrics, name: "userMetrics" },
-      { ref: api.garmin.public.pullHRV, name: "hrv" },
-      { ref: api.garmin.public.pullStressDetails, name: "stressDetails" },
-      { ref: api.garmin.public.pullPulseOx, name: "pulseOx" },
-      { ref: api.garmin.public.pullRespiration, name: "respiration" },
-    ];
-    const synced: Record<string, number> = {};
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-    for (const { ref, name } of pullFns) {
-      try {
-        const result = await ctx.runAction(ref, sharedArgs);
-        Object.assign(synced, result.synced);
-        errors.push(...result.errors);
-      } catch (err) {
-        errors.push({
-          type: name,
-          id: "pull",
-          error: err instanceof Error ? err.message : String(err),
-        });
-      }
-    }
-    return { synced, errors };
-  },
-});
-/**
- * Incremental Garmin sync for an already-connected user.
- *
- * Looks up the stored tokens, refreshes if expired, and syncs all data
- * types for the specified time range (defaults to last 30 days).
- */
-
-export const syncGarmin = action({
-  args: {
-    userId: v.string(),
-    clientId: v.string(),
-    clientSecret: v.string(),
-    startTimeInSeconds: v.optional(v.number()),
-    endTimeInSeconds: v.optional(v.number()),
-  },
-  handler: async (ctx, args): Promise<{
-    synced: Record<string, number>;
-    errors: Array<{ type: string; id: string; error: string }>;
-  }> => {
-    const connection: Doc<"connections"> | null = await ctx.runQuery(
-      internal.private.getConnectionByProvider,
-      { userId: args.userId, provider: "GARMIN" },
-    );
-    if (!connection) {
-      throw new Error(
-        `No Garmin connection found for user "${args.userId}". ` +
-        "Connect to Garmin first via getGarminAuthUrl.",
-      );
-    }
-    if (!connection.active) {
-      throw new Error(
-        `Garmin connection for user "${args.userId}" is inactive. Reconnect first.`,
-      );
-    }
-
-    const connectionId = connection._id;
-
-    const tokenDoc: Doc<"providerTokens"> | null = await ctx.runQuery(internal.garmin.private.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;
-
-    // Refresh the token if it's expired or about to expire
-    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;
-      const _refreshed: null = await ctx.runMutation(internal.garmin.private.storeTokens, {
-        connectionId,
-        accessToken: refreshed.access_token,
-        refreshToken: refreshed.refresh_token,
-        expiresAt: newExpiresAt,
-      });
-    }
-
-    // Lazy backfill: resolve Garmin user ID if missing (for webhook mapping)
-    if (!connection.providerUserId) {
-      const wellnessClient = createWellnessClient(accessToken);
-      const { data: userIdData } = await sdkUserId({ client: wellnessClient });
-      const garminUserId = userIdData?.userId ?? null;
-      if (garminUserId) {
-        const _updated: null = await ctx.runMutation(api.public.updateConnection, {
-          connectionId,
-          providerUserId: garminUserId,
-        });
-      }
-    }
-
-    const now = Math.floor(Date.now() / 1000);
-    const timeRange = {
-      uploadStartTimeInSeconds:
-        args.startTimeInSeconds ?? now - DEFAULT_SYNC_DAYS * 86400,
-      uploadEndTimeInSeconds: args.endTimeInSeconds ?? now,
-    };
-
-    const result = await ctx.runAction(api.garmin.public.syncAllTypes, {
-      accessToken,
-      connectionId,
-      userId: args.userId,
-      uploadStartTimeInSeconds: timeRange.uploadStartTimeInSeconds,
-      uploadEndTimeInSeconds: timeRange.uploadEndTimeInSeconds,
-    });
-
-    const _updated: null = await ctx.runMutation(api.public.updateConnection, {
-      connectionId,
-      lastDataUpdate: new Date().toISOString(),
-    });
-
-    return result;
-  },
-});
-
-/**
- * Fetch and ingest all Garmin wellness data types for a time range.
- *
- * Called by syncGarmin after obtaining a valid access token.
- * after obtaining a valid access token.
- */
-export const syncAllTypes = action({
-  args: {
-    accessToken: v.string(),
-    connectionId: v.id("connections"),
-    userId: v.string(),
-    uploadStartTimeInSeconds: v.number(),
-    uploadEndTimeInSeconds: v.number(),
-  },
-  handler: async (ctx, args) => {
-    const { accessToken, connectionId, userId } = args;
-    const timeRange = {
-      uploadStartTimeInSeconds: args.uploadStartTimeInSeconds,
-      uploadEndTimeInSeconds: args.uploadEndTimeInSeconds,
-    };
-    const wellnessClient = createWellnessClient(accessToken);
-    const query = timeRangeQuery(timeRange, accessToken);
-
-    const synced = {
-      activities: 0, dailies: 0, sleep: 0, body: 0, menstruation: 0,
-      bloodPressures: 0, skinTemp: 0, userMetrics: 0,
-      hrv: 0, stressDetails: 0, pulseOx: 0, respiration: 0,
-    };
-    const errors: Array<{ type: string; id: string; error: string }> = [];
-
-    // ── Activities ──────────────────────────────────────────────────────────
-    try {
-      const { data: activities, error } = await getActivities({ client: wellnessClient, query });
-      if (error || !activities) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const activity of activities) {
-        try {
-          const data = transformActivity(activity);
-          await ctx.runMutation(api.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 { data: dailies, error } = await getDailies({ client: wellnessClient, query });
-      if (error || !dailies) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const daily of dailies) {
-        try {
-          const data = transformDailies(daily);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestDaily, {
-            connectionId,
-            userId,
-            ...data,
-          } as never);
-          synced.dailies++;
-        } catch (err) {
-          errors.push({
-            type: "daily",
-            id: daily.summaryId ?? daily.calendarDate ?? "unknown",
-            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 { data: sleeps, error } = await getSleeps({ client: wellnessClient, query });
-      if (error || !sleeps) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const sleep of sleeps) {
-        try {
-          const data = transformSleeps(sleep);
-          await ctx.runMutation(api.public.ingestSleep, {
-            connectionId,
-            userId,
-            ...data,
-          } as never);
-          synced.sleep++;
-        } catch (err) {
-          errors.push({
-            type: "sleep",
-            id: sleep.summaryId ?? sleep.calendarDate ?? "unknown",
-            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 { data: bodyComps, error } = await getBodyComps({ client: wellnessClient, query });
-      if (error || !bodyComps) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const body of bodyComps) {
-        try {
-          const data = transformBodyComposition(body);
-          if (!data) continue;
-          await ctx.runMutation(api.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 { data: records, error } = await getMct({ client: wellnessClient, query });
-      if (error || !records) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const record of records) {
-        try {
-          const data = transformMenstrualCycleTracking(record);
-          await ctx.runMutation(api.public.ingestMenstruation, {
-            connectionId,
-            userId,
-            ...data,
-          } as never);
-          synced.menstruation++;
-        } catch (err) {
-          errors.push({
-            type: "menstruation",
-            id: record.summaryId ?? record.periodStartDate ?? "unknown",
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-    } catch (err) {
-      errors.push({
-        type: "menstruation",
-        id: "fetch",
-        error: err instanceof Error ? err.message : String(err),
-      });
-    }
-
-    // ── Blood Pressures (→ body) ───────────────────────────────────────────
-    try {
-      const { data: bpRecords, error } = await getBloodPressures({ client: wellnessClient, query });
-      if (error || !bpRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const bp of bpRecords) {
-        try {
-          const data = transformBloodPressure(bp);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestBody, {
-            connectionId, userId, ...data,
-          } as never);
-          synced.bloodPressures++;
-        } catch (err) {
-          errors.push({
-            type: "bloodPressure",
-            id: bp.summaryId ?? String(bp.measurementTimeInSeconds),
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "bloodPressure", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    // ── Skin Temperature (→ body) ──────────────────────────────────────────
-    try {
-      const { data: skinRecords, error } = await getSkinTemp({ client: wellnessClient, query });
-      if (error || !skinRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const skin of skinRecords) {
-        try {
-          const data = transformSkinTemperature(skin);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestBody, {
-            connectionId, userId, ...data,
-          } as never);
-          synced.skinTemp++;
-        } catch (err) {
-          errors.push({
-            type: "skinTemp",
-            id: skin.summaryId ?? skin.calendarDate ?? "unknown",
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "skinTemp", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    // ── User Metrics (→ body) ──────────────────────────────────────────────
-    try {
-      const { data: metricsRecords, error } = await getUserMetrics({ client: wellnessClient, query });
-      if (error || !metricsRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const metrics of metricsRecords) {
-        try {
-          const data = transformUserMetrics(metrics);
-          if (!data) continue;
-          await ctx.runMutation(api.public.ingestBody, {
-            connectionId, userId, ...data,
-          } as never);
-          synced.userMetrics++;
-        } catch (err) {
-          errors.push({
-            type: "userMetrics",
-            id: metrics.summaryId ?? metrics.calendarDate ?? "unknown",
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "userMetrics", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    // ── HRV (enriches daily) ──────────────────────────────────────────────
-    try {
-      const { data: hrvRecords, error } = await getHrv({ client: wellnessClient, query });
-      if (error || !hrvRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const hrv of hrvRecords) {
-        try {
-          const data = transformHRVSummary(hrv);
-          if (data) {
-            await ctx.runMutation(api.public.ingestDaily, {
-              connectionId, userId, ...data,
-            } as never);
-            synced.hrv++;
-          }
-        } catch (err) {
-          errors.push({
-            type: "hrv",
-            id: hrv.summaryId ?? hrv.calendarDate ?? "unknown",
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "hrv", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    // ── Stress Details (enriches daily) ────────────────────────────────────
-    try {
-      const { data: stressRecords, error } = await getStressDetails({ client: wellnessClient, query });
-      if (error || !stressRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const stress of stressRecords) {
-        try {
-          const data = transformStress(stress);
-          if (data) {
-            await ctx.runMutation(api.public.ingestDaily, {
-              connectionId, userId, ...data,
-            } as never);
-            synced.stressDetails++;
-          }
-        } catch (err) {
-          errors.push({
-            type: "stressDetails",
-            id: stress.summaryId ?? stress.calendarDate ?? "unknown",
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "stressDetails", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    // ── Pulse Ox (enriches daily) ──────────────────────────────────────────
-    try {
-      const { data: pulseOxRecords, error } = await getPulseox({ client: wellnessClient, query });
-      if (error || !pulseOxRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const po of pulseOxRecords) {
-        try {
-          const data = transformPulseOx(po);
-          if (data) {
-            await ctx.runMutation(api.public.ingestDaily, {
-              connectionId, userId, ...data,
-            } as never);
-            synced.pulseOx++;
-          }
-        } catch (err) {
-          errors.push({
-            type: "pulseOx",
-            id: po.summaryId ?? po.calendarDate ?? "unknown",
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "pulseOx", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    // ── Respiration (enriches daily) ───────────────────────────────────────
-    try {
-      const { data: respRecords, error } = await getRespiration({ client: wellnessClient, query });
-      if (error || !respRecords) throw new Error(error ? JSON.stringify(error) : "No data");
-      for (const resp of respRecords) {
-        try {
-          const data = transformRespiration(resp);
-          if (data) {
-            await ctx.runMutation(api.public.ingestDaily, {
-              connectionId, userId, ...data,
-            } as never);
-            synced.respiration++;
-          }
-        } catch (err) {
-          errors.push({
-            type: "respiration",
-            id: resp.summaryId ?? "unknown",
-            error: err instanceof Error ? err.message : String(err),
-          });
-        }
-      }
-    } catch (err) {
-      errors.push({ type: "respiration", id: "fetch", error: err instanceof Error ? err.message : String(err) });
-    }
-
-    return { synced, errors };
-  },
-});
-
-// ─── Push ───────────────────────────────────────────────────────────────────
-
-/**
- * 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()),
-  },
-  handler: async (ctx, args): Promise<{ garminWorkoutId: number; garminScheduleId: number | null }> => {
-    const connection: Doc<"connections"> | null = await ctx.runQuery(
-      internal.private.getConnectionByProvider,
-      { userId: args.userId, provider: "GARMIN" },
-    );
-    if (!connection) {
-      throw new Error(
-        `No Garmin connection found for user "${args.userId}". ` +
-        "Connect to Garmin first via getGarminAuthUrl.",
-      );
-    }
-    if (!connection.active) {
-      throw new Error(
-        `Garmin connection for user "${args.userId}" is inactive. Reconnect first.`,
-      );
-    }
-
-    const connectionId = connection._id;
-
-    const tokenDoc: Doc<"providerTokens"> | null = await ctx.runQuery(internal.garmin.private.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.",
-      );
-    }
-
-    // Always force-refresh the token for Training API calls to rule out
-    // stale tokens (the initial sync swallows 401 errors silently).
-    let accessToken = tokenDoc.accessToken;
-
-    if (tokenDoc.refreshToken) {
-      try {
-        const refreshed = await refreshToken({
-          clientId: args.clientId,
-          clientSecret: args.clientSecret,
-          refreshToken: tokenDoc.refreshToken,
-        });
-
-        accessToken = refreshed.access_token;
-        const nowSeconds = Math.floor(Date.now() / 1000);
-        const newExpiresAt = nowSeconds + refreshed.expires_in;
-        const _refreshed: null = await ctx.runMutation(internal.garmin.private.storeTokens, {
-          connectionId,
-          accessToken: refreshed.access_token,
-          refreshToken: refreshed.refresh_token,
-          expiresAt: newExpiresAt,
-        });
-      } catch (refreshErr) {
-        throw new Error(
-          `Garmin token refresh failed: ${refreshErr instanceof Error ? refreshErr.message : String(refreshErr)}. ` +
-          "The user may need to reconnect their Garmin account.",
-        );
-      }
-    }
-
-    const plannedWorkout: Doc<"plannedWorkouts"> | null = await ctx.runQuery(
-      api.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 trainingClient = createTrainingClient(accessToken);
-
-    const { data: created, error: createError } = await sdkCreateWorkoutV2({
-      client: trainingClient,
-      body: garminWorkout,
-    });
-    if (createError || !created) {
-      throw new Error(
-        `Garmin API error creating workout: ${createError ? JSON.stringify(createError) : "No data"}`,
-      );
-    }
-
-    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 { data: scheduleId, error: scheduleError } = await sdkCreateWorkoutSchedule({
-        client: trainingClient,
-        body: { workoutId: Number(created.workoutId), date: plannedDate },
-      });
-      if (scheduleError) {
-        throw new Error(
-          `Garmin API error creating schedule: ${JSON.stringify(scheduleError)}`,
-        );
-      }
-      garminScheduleId = scheduleId ?? null;
-    }
-
-    // Store the Garmin workout/schedule IDs back on the planned workout
-    // so the host app can match completed activities to planned sessions.
-    const _ingested: Id<"plannedWorkouts"> = await ctx.runMutation(api.public.ingestPlannedWorkout, {
-      ...plannedWorkout,
-      _id: undefined,
-      _creationTime: undefined,
-      metadata: {
-        ...plannedWorkout.metadata,
-        provider_workout_id: String(created.workoutId),
-        provider_schedule_id:
-          garminScheduleId != null ? String(garminScheduleId) : undefined,
-      },
-    } as never);
-
-    return {
-      garminWorkoutId: created.workoutId,
-      garminScheduleId,
-    };
-  },
-});
-
+// ─── Garmin Public Actions ───────────────────────────────────────────────────
+// Public actions that handle the full Garmin OAuth 2.0 PKCE + sync lifecycle.
+// The host app calls these through the Soma class, which threads the
+// credentials automatically from env vars or constructor config.
+
+import { v } from "convex/values";
+import { action } from "../_generated/server";
+import type { Doc, Id } from "../_generated/dataModel";
+import { generateState } from "../utils.js";
+import {
+  generateCodeVerifier,
+  generateCodeChallenge,
+  buildAuthUrl,
+  exchangeCode,
+  refreshToken,
+} from "./auth.js";
+import {
+  createWellnessClient,
+  createTrainingClient,
+} from "./client.js";
+import { buildTimeRangeQuery } from "./utils.js";
+import {
+  createWorkoutV2 as sdkCreateWorkoutV2,
+  createWorkoutSchedule as sdkCreateWorkoutSchedule,
+  updateWorkoutV2 as sdkUpdateWorkoutV2,
+  updateWorkoutSchedule as sdkUpdateWorkoutSchedule,
+  deleteWorkoutV2 as sdkDeleteWorkoutV2,
+  deleteWorkoutSchedule as sdkDeleteWorkoutSchedule,
+} from "./types/trainingApiWorkouts/sdk.gen";
+import {
+  userId as sdkUserId,
+  dereg as sdkDereg,
+  getActivities,
+  getDailies,
+  getSleeps,
+  getBodyComps,
+  getMct,
+  getBloodPressures,
+  getSkinTemp,
+  getUserMetrics,
+  getHrv,
+  getStressDetails,
+  getPulseox,
+  getRespiration,
+} from "./types/wellnessApi/sdk.gen";
+import { transformActivity } from "./transform/activity.js";
+import { transformDailies } from "./transform/dailies.js";
+import { transformSleeps } from "./transform/sleeps.js";
+import { transformBodyComposition } from "./transform/bodyCompositions.js";
+import { transformMenstrualCycleTracking } from "./transform/menstrualCycleTracking.js";
+import { transformBloodPressure } from "./transform/bloodPressure.js";
+import { transformSkinTemperature } from "./transform/skinTemperature.js";
+import { transformUserMetrics } from "./transform/userMetrics.js";
+import { transformHRVSummary } from "./transform/hrvSummary.js";
+import { transformStress } from "./transform/stress.js";
+import { transformPulseOx } from "./transform/pulseOx.js";
+import { transformRespiration } from "./transform/respiration.js";
+import { transformPlannedWorkoutToGarmin } from "./transform/plannedWorkout.js";
+import { api, internal } from "../_generated/api";
+
+// ─── OAuth ──────────────────────────────────────────────────────────────────
+
+export const getGarminAuthUrl = action({
+  args: {
+    clientId: v.string(),
+    redirectUri: v.optional(v.string()),
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const state = generateState();
+
+    const authUrl = buildAuthUrl({
+      clientId: args.clientId,
+      codeChallenge,
+      redirectUri: args.redirectUri,
+      state,
+    });
+
+    await ctx.runMutation(internal.garmin.private.storePendingOAuth, {
+      provider: "GARMIN",
+      state,
+      codeVerifier,
+      userId: args.userId,
+    });
+
+    return { authUrl, state, codeVerifier };
+  },
+});
+
+export const completeGarminOAuth = action({
+  args: {
+    code: v.string(),
+    state: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    redirectUri: v.optional(v.string()),
+  },
+  handler: async (ctx, args): Promise<{
+    connectionId: Id<"connections">;
+    userId: string;
+  }> => {
+    const pending: Doc<"pendingOAuth"> | null = await ctx.runQuery(internal.garmin.private.getPendingOAuth, {
+      state: args.state,
+    });
+    if (!pending) {
+      throw new Error(
+        "No pending Garmin OAuth state found for this state parameter. " +
+        "The authorization may have expired or was already used.",
+      );
+    }
+
+    if (!pending.codeVerifier) {
+      throw new Error(
+        "No code verifier found for this state parameter. " +
+        "The authorization may have expired or was already used.",
+      );
+    }
+
+    const tokenResult = await exchangeCode({
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      code: args.code,
+      codeVerifier: pending.codeVerifier,
+      redirectUri: args.redirectUri,
+    });
+
+    const _deleted: null = await ctx.runMutation(internal.garmin.private.deletePendingOAuth, {
+      state: args.state,
+    });
+
+    const connectionId: Id<"connections"> = await ctx.runMutation(api.public.connect, {
+      userId: pending.userId,
+      provider: "GARMIN",
+    });
+
+    const expiresAt = Math.floor(Date.now() / 1000) + tokenResult.expires_in;
+    const _stored: null = await ctx.runMutation(internal.garmin.private.storeTokens, {
+      connectionId,
+      accessToken: tokenResult.access_token,
+      refreshToken: tokenResult.refresh_token,
+      expiresAt,
+    });
+
+    // Best-effort: resolve Garmin user ID for webhook mapping
+    const wellnessClient = createWellnessClient(tokenResult.access_token);
+    const { data: userIdData } = await sdkUserId({ client: wellnessClient });
+    const garminUserId = userIdData?.userId ?? null;
+    if (garminUserId) {
+      const _updated: null = await ctx.runMutation(api.public.updateConnection, {
+        connectionId,
+        providerUserId: garminUserId,
+      });
+    }
+
+    return {
+      connectionId,
+      userId: pending.userId,
+    };
+  },
+});
+
+export const disconnectGarmin = action({
+  args: {
+    userId: v.string(),
+  },
+  handler: async (ctx, args) => {
+    const connection: Doc<"connections"> | null = await ctx.runQuery(
+      internal.private.getConnectionByProvider,
+      { userId: args.userId, provider: "GARMIN" },
+    );
+    if (!connection) {
+      throw new Error(
+        `No Garmin connection found for user "${args.userId}".`,
+      );
+    }
+
+    const connectionId = connection._id;
+
+    // Best-effort: deregister user at Garmin
+    const tokenDoc: Doc<"providerTokens"> | null = await ctx.runQuery(internal.garmin.private.getTokens, {
+      connectionId,
+    });
+    if (tokenDoc) {
+      try {
+        const wellnessClient = createWellnessClient(tokenDoc.accessToken);
+        await sdkDereg({ client: wellnessClient });
+      } catch {
+        // Deregistration is best-effort; proceed with local cleanup
+      }
+    }
+
+    const _deleted: null = await ctx.runMutation(internal.garmin.private.deleteTokens, { connectionId });
+
+    const _disconnected: null = await ctx.runMutation(api.public.disconnect, {
+      userId: args.userId,
+      provider: "GARMIN",
+    });
+
+    return null;
+  },
+});
+
+// ─── Pull ───────────────────────────────────────────────────────────────────
+
+export const pullActivities = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      {
+        userId: args.userId,
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+      },
+    );
+
+    const timeRangeQuery = buildTimeRangeQuery(args, accessToken);
+
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { activities: 0 };
+    const errors: Array<{ type: "activity"; id: string; error: string }> = [];
+
+    try {
+      const { data: activities, error } = await getActivities({
+        client: wellnessClient,
+        query: timeRangeQuery,
+      });
+
+      if (error || !activities) {
+        throw new Error(error ? JSON.stringify(error) : "No data");
+      }
+
+      for (const activity of activities) {
+        try {
+          const data = transformActivity(activity);
+          await ctx.runMutation(api.public.ingestActivity, {
+            connectionId,
+            userId: args.userId,
+            ...data,
+          });
+          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),
+      });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+
+    return { synced, errors };
+  },
+});
+
+export const pullDailies = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { dailies: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: dailies, error } = await getDailies({ client: wellnessClient, query });
+      if (error || !dailies) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const daily of dailies) {
+        try {
+          const data = transformDailies(daily);
+          if (!data) continue;
+          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
+          synced.dailies++;
+        } catch (err) {
+          errors.push({ type: "daily", id: daily.summaryId ?? daily.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "daily", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullSleep = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { sleep: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: sleeps, error } = await getSleeps({ client: wellnessClient, query });
+      if (error || !sleeps) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const sleep of sleeps) {
+        try {
+          const data = transformSleeps(sleep);
+          await ctx.runMutation(api.public.ingestSleep, { connectionId, userId: args.userId, ...data });
+          synced.sleep++;
+        } catch (err) {
+          errors.push({ type: "sleep", id: sleep.summaryId ?? sleep.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "sleep", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullBody = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { body: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: bodyComps, error } = await getBodyComps({ client: wellnessClient, query });
+      if (error || !bodyComps) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const body of bodyComps) {
+        try {
+          const data = transformBodyComposition(body);
+          if (!data) continue;
+          await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
+          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) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullMenstruation = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { menstruation: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: records, error } = await getMct({ client: wellnessClient, query });
+      if (error || !records) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const record of records) {
+        try {
+          const data = transformMenstrualCycleTracking(record);
+          await ctx.runMutation(api.public.ingestMenstruation, { connectionId, userId: args.userId, ...data });
+          synced.menstruation++;
+        } catch (err) {
+          errors.push({ type: "menstruation", id: record.summaryId ?? record.periodStartDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "menstruation", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullBloodPressures = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { bloodPressures: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: bpRecords, error } = await getBloodPressures({ client: wellnessClient, query });
+      if (error || !bpRecords) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const bp of bpRecords) {
+        try {
+          const data = transformBloodPressure(bp);
+          if (!data) continue;
+          await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
+          synced.bloodPressures++;
+        } catch (err) {
+          errors.push({ type: "bloodPressure", id: bp.summaryId ?? String(bp.measurementTimeInSeconds), error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "bloodPressure", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullSkinTemperature = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { skinTemp: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: skinRecords, error } = await getSkinTemp({ client: wellnessClient, query });
+      if (error || !skinRecords) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const skin of skinRecords) {
+        try {
+          const data = transformSkinTemperature(skin);
+          if (!data) continue;
+          await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
+          synced.skinTemp++;
+        } catch (err) {
+          errors.push({ type: "skinTemp", id: skin.summaryId ?? skin.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "skinTemp", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullUserMetrics = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { userMetrics: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: metricsRecords, error } = await getUserMetrics({ client: wellnessClient, query });
+      if (error || !metricsRecords) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const metrics of metricsRecords) {
+        try {
+          const data = transformUserMetrics(metrics);
+          if (!data) continue;
+          await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
+          synced.userMetrics++;
+        } catch (err) {
+          errors.push({ type: "userMetrics", id: metrics.summaryId ?? metrics.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "userMetrics", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullHRV = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { hrv: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: hrvRecords, error } = await getHrv({ client: wellnessClient, query });
+      if (error || !hrvRecords) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const hrv of hrvRecords) {
+        try {
+          const data = transformHRVSummary(hrv);
+          if (!data) continue;
+          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
+          synced.hrv++;
+        } catch (err) {
+          errors.push({ type: "hrv", id: hrv.summaryId ?? hrv.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "hrv", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullStressDetails = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { stressDetails: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: stressRecords, error } = await getStressDetails({ client: wellnessClient, query });
+      if (error || !stressRecords) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const stress of stressRecords) {
+        try {
+          const data = transformStress(stress);
+          if (!data) continue;
+          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
+          synced.stressDetails++;
+        } catch (err) {
+          errors.push({ type: "stressDetails", id: stress.summaryId ?? stress.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "stressDetails", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullPulseOx = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { pulseOx: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: pulseOxRecords, error } = await getPulseox({ client: wellnessClient, query });
+      if (error || !pulseOxRecords) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const po of pulseOxRecords) {
+        try {
+          const data = transformPulseOx(po);
+          if (!data) continue;
+          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
+          synced.pulseOx++;
+        } catch (err) {
+          errors.push({ type: "pulseOx", id: po.summaryId ?? po.calendarDate ?? "unknown", error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "pulseOx", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullRespiration = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const query = buildTimeRangeQuery(args, accessToken);
+    const wellnessClient = createWellnessClient(accessToken);
+    const synced = { respiration: 0 };
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+
+    try {
+      const { data: respRecords, error } = await getRespiration({ client: wellnessClient, query });
+      if (error || !respRecords) throw new Error(error ? JSON.stringify(error) : "No data");
+      for (const resp of respRecords) {
+        try {
+          const data = transformRespiration(resp);
+          if (!data) continue;
+          await ctx.runMutation(api.public.ingestDaily, { connectionId, userId: args.userId, ...data });
+          synced.respiration++;
+        } catch (err) {
+          errors.push({ type: "respiration", id: resp.summaryId ?? "unknown", error: err instanceof Error ? err.message : String(err) });
+        }
+      }
+    } catch (err) {
+      errors.push({ type: "respiration", id: "fetch", error: err instanceof Error ? err.message : String(err) });
+    }
+
+    await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
+    return { synced, errors };
+  },
+});
+
+export const pullAll = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const sharedArgs = {
+      userId: args.userId,
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      startTimeInSeconds: args.startTimeInSeconds,
+      endTimeInSeconds: args.endTimeInSeconds,
+    };
+    const pullFns = [
+      { ref: api.garmin.public.pullActivities, name: "activities" },
+      { ref: api.garmin.public.pullDailies, name: "dailies" },
+      { ref: api.garmin.public.pullSleep, name: "sleep" },
+      { ref: api.garmin.public.pullBody, name: "body" },
+      { ref: api.garmin.public.pullMenstruation, name: "menstruation" },
+      { ref: api.garmin.public.pullBloodPressures, name: "bloodPressures" },
+      { ref: api.garmin.public.pullSkinTemperature, name: "skinTemp" },
+      { ref: api.garmin.public.pullUserMetrics, name: "userMetrics" },
+      { ref: api.garmin.public.pullHRV, name: "hrv" },
+      { ref: api.garmin.public.pullStressDetails, name: "stressDetails" },
+      { ref: api.garmin.public.pullPulseOx, name: "pulseOx" },
+      { ref: api.garmin.public.pullRespiration, name: "respiration" },
+    ];
+    const synced: Record<string, number> = {};
+    const errors: Array<{ type: string; id: string; error: string }> = [];
+    for (const { ref, name } of pullFns) {
+      try {
+        const result = await ctx.runAction(ref, sharedArgs);
+        Object.assign(synced, result.synced);
+        errors.push(...result.errors);
+      } catch (err) {
+        errors.push({
+          type: name,
+          id: "pull",
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+    return { synced, errors };
+  },
+});
+
+
+// ─── Push ───────────────────────────────────────────────────────────────────
+
+export const pushWorkout = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    plannedWorkoutId: v.string(),
+    workoutProvider: v.optional(v.string()),
+  },
+  handler: async (ctx, args): Promise<{ garminWorkoutId: number }> => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const plannedWorkout: Doc<"plannedWorkouts"> | null = await ctx.runQuery(
+      api.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 trainingClient = createTrainingClient(accessToken);
+
+    const existingWorkoutId = plannedWorkout.metadata?.provider_workout_id;
+    let workoutId: number;
+
+    if (existingWorkoutId) {
+      // Update existing workout on Garmin
+      const numericId = Number(existingWorkoutId);
+      garminWorkout.workoutId = numericId;
+      const { error: updateError } = await sdkUpdateWorkoutV2({
+        client: trainingClient,
+        body: garminWorkout,
+        path: { workoutId: numericId },
+      });
+      if (updateError) {
+        throw new Error(
+          `Garmin API error updating workout: ${JSON.stringify(updateError)}`,
+        );
+      }
+      workoutId = numericId;
+    } else {
+      // Create new workout on Garmin
+      const { data: created, error: createError } = await sdkCreateWorkoutV2({
+        client: trainingClient,
+        body: garminWorkout,
+      });
+      if (createError || !created) {
+        throw new Error(
+          `Garmin API error creating workout: ${createError ? JSON.stringify(createError) : "No data"}`,
+        );
+      }
+      if (!created.workoutId) {
+        throw new Error("Garmin API did not return a workoutId after creation.");
+      }
+      workoutId = created.workoutId;
+    }
+
+    // Persist the Garmin workout ID back on the planned workout
+    const _ingested: Id<"plannedWorkouts"> = await ctx.runMutation(api.public.ingestPlannedWorkout, {
+      ...plannedWorkout,
+      _id: undefined,
+      _creationTime: undefined,
+      metadata: {
+        ...plannedWorkout.metadata,
+        provider_workout_id: String(workoutId),
+      },
+    } as never);
+
+    return { garminWorkoutId: workoutId };
+  },
+});
+
+export const pushSchedule = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    plannedWorkoutId: v.string(),
+    date: v.optional(v.string()),
+  },
+  handler: async (ctx, args): Promise<{ garminScheduleId: number }> => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const plannedWorkout: Doc<"plannedWorkouts"> | null = await ctx.runQuery(
+      api.public.getPlannedWorkout,
+      { plannedWorkoutId: args.plannedWorkoutId as never },
+    );
+    if (!plannedWorkout) {
+      throw new Error(`Planned workout "${args.plannedWorkoutId}" not found.`);
+    }
+
+    const providerWorkoutId = plannedWorkout.metadata?.provider_workout_id;
+    if (!providerWorkoutId) {
+      throw new Error(
+        "No Garmin workout ID found on this planned workout. Push the workout first via pushWorkout.",
+      );
+    }
+
+    const scheduleDate = args.date ?? plannedWorkout.metadata?.planned_date;
+    if (!scheduleDate) {
+      throw new Error(
+        "No date provided and no planned_date on the workout. Provide a date argument.",
+      );
+    }
+
+    const trainingClient = createTrainingClient(accessToken);
+
+    const existingScheduleId = plannedWorkout.metadata?.provider_schedule_id;
+    let scheduleId: number;
+
+    if (existingScheduleId) {
+      // Update existing schedule on Garmin
+      const numericScheduleId = Number(existingScheduleId);
+      const { error: updateError } = await sdkUpdateWorkoutSchedule({
+        client: trainingClient,
+        body: { workoutId: Number(providerWorkoutId), date: scheduleDate },
+        path: { workoutScheduleId: numericScheduleId },
+      });
+      if (updateError) {
+        throw new Error(
+          `Garmin API error updating schedule: ${JSON.stringify(updateError)}`,
+        );
+      }
+      scheduleId = numericScheduleId;
+    } else {
+      // Create new schedule on Garmin
+      const { data: createdScheduleId, error: scheduleError } = await sdkCreateWorkoutSchedule({
+        client: trainingClient,
+        body: { workoutId: Number(providerWorkoutId), date: scheduleDate },
+      });
+      if (scheduleError) {
+        throw new Error(
+          `Garmin API error creating schedule: ${JSON.stringify(scheduleError)}`,
+        );
+      }
+      if (createdScheduleId == null) {
+        throw new Error("Garmin API did not return a scheduleId after creation.");
+      }
+      scheduleId = createdScheduleId;
+    }
+
+    // Persist the Garmin schedule ID back on the planned workout
+    const _ingested: Id<"plannedWorkouts"> = await ctx.runMutation(api.public.ingestPlannedWorkout, {
+      ...plannedWorkout,
+      _id: undefined,
+      _creationTime: undefined,
+      metadata: {
+        ...plannedWorkout.metadata,
+        provider_schedule_id: String(scheduleId),
+      },
+    } as never);
+
+    return { garminScheduleId: scheduleId };
+  },
+});
+
+// ─── Delete ───────────────────────────────────────────────────────────────────
+
+export const deleteWorkout = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    plannedWorkoutId: v.string(),
+  },
+  handler: async (ctx, args): Promise<null> => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const plannedWorkout: Doc<"plannedWorkouts"> | null = await ctx.runQuery(
+      api.public.getPlannedWorkout,
+      { plannedWorkoutId: args.plannedWorkoutId as never },
+    );
+    if (!plannedWorkout) {
+      throw new Error(`Planned workout "${args.plannedWorkoutId}" not found.`);
+    }
+
+    const providerWorkoutId = plannedWorkout.metadata?.provider_workout_id;
+    if (!providerWorkoutId) {
+      throw new Error("No Garmin workout ID found on this planned workout. Nothing to delete.");
+    }
+
+    const trainingClient = createTrainingClient(accessToken);
+
+    const { error: deleteError } = await sdkDeleteWorkoutV2({
+      client: trainingClient,
+      path: { workoutId: Number(providerWorkoutId) },
+    });
+    if (deleteError) {
+      throw new Error(
+        `Garmin API error deleting workout: ${JSON.stringify(deleteError)}`,
+      );
+    }
+
+    // Clear both provider IDs — deleting a workout on Garmin cascades to its schedules
+    const _ingested: Id<"plannedWorkouts"> = await ctx.runMutation(api.public.ingestPlannedWorkout, {
+      ...plannedWorkout,
+      _id: undefined,
+      _creationTime: undefined,
+      metadata: {
+        ...plannedWorkout.metadata,
+        provider_workout_id: undefined,
+        provider_schedule_id: undefined,
+      },
+    } as never);
+
+    return null;
+  },
+});
+
+export const deleteSchedule = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    plannedWorkoutId: v.string(),
+  },
+  handler: async (ctx, args): Promise<null> => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.garmin.private.resolveConnectionAndAccessToken,
+      { userId: args.userId, clientId: args.clientId, clientSecret: args.clientSecret },
+    );
+
+    const plannedWorkout: Doc<"plannedWorkouts"> | null = await ctx.runQuery(
+      api.public.getPlannedWorkout,
+      { plannedWorkoutId: args.plannedWorkoutId as never },
+    );
+    if (!plannedWorkout) {
+      throw new Error(`Planned workout "${args.plannedWorkoutId}" not found.`);
+    }
+
+    const providerScheduleId = plannedWorkout.metadata?.provider_schedule_id;
+    if (!providerScheduleId) {
+      throw new Error("No Garmin schedule ID found on this planned workout. Nothing to delete.");
+    }
+
+    const trainingClient = createTrainingClient(accessToken);
+
+    const { error: deleteError } = await sdkDeleteWorkoutSchedule({
+      client: trainingClient,
+      path: { workoutScheduleId: Number(providerScheduleId) },
+    });
+    if (deleteError) {
+      throw new Error(
+        `Garmin API error deleting schedule: ${JSON.stringify(deleteError)}`,
+      );
+    }
+
+    // Clear only the schedule ID — the workout still exists on Garmin
+    const _ingested: Id<"plannedWorkouts"> = await ctx.runMutation(api.public.ingestPlannedWorkout, {
+      ...plannedWorkout,
+      _id: undefined,
+      _creationTime: undefined,
+      metadata: {
+        ...plannedWorkout.metadata,
+        provider_schedule_id: undefined,
+      },
+    } as never);
+
+    return null;
+  },
+});
+