@nativesquare/soma 0.14.1 → 0.16.0

package/src/client/healthkit.ts

@@ -0,0 +1,791 @@
+import type { SomaComponent } from "./index.js";
+import type { MutationCtx, SomaError } from "./types.js";
+import type {
+  HKWorkout,
+  HKCategorySample,
+  HKQuantitySample,
+  HKActivitySummary,
+  HKCharacteristics,
+} from "../component/healthkit/types.js";
+import { transformWorkout } from "../component/healthkit/transform/activity.js";
+import { transformSleep } from "../component/healthkit/transform/sleep.js";
+import { transformBody } from "../component/healthkit/transform/body.js";
+import {
+  transformDaily,
+  transformDailyFromSummary,
+} from "../component/healthkit/transform/daily.js";
+import { transformNutrition } from "../component/healthkit/transform/nutrition.js";
+import { transformMenstruation } from "../component/healthkit/transform/menstruation.js";
+import { transformAthlete } from "../component/healthkit/transform/athlete.js";
+
+const PROVIDER = "APPLE";
+
+type SyncResult<T extends Record<string, number>> = {
+  data: { synced: T };
+  errors: SomaError[];
+};
+
+/**
+ * Client class for Apple HealthKit integration with Soma.
+ *
+ * Unlike {@link import("./strava.js").SomaStrava | SomaStrava} and
+ * {@link import("./garmin.js").SomaGarmin | SomaGarmin}, HealthKit is an
+ * on-device provider — data is queried locally on iOS, not fetched from a
+ * cloud API. This class wraps the transform + ingest pipeline so the host
+ * app gets the same ergonomic interface as cloud providers.
+ *
+ * No configuration is required — HealthKit has no OAuth credentials.
+ *
+ * @example
+ * ```ts
+ * // Sync workouts received from the React Native client:
+ * const result = await soma.healthkit.syncActivities(ctx, {
+ *   userId: "user_123",
+ *   workouts: hkWorkouts,
+ * });
+ * // result: { data: { synced: { activities: 5 } }, errors: [] }
+ *
+ * // Or sync everything at once:
+ * await soma.healthkit.syncAll(ctx, {
+ *   userId: "user_123",
+ *   workouts: hkWorkouts,
+ *   sleepSessions: [nightSamples],
+ *   bodySamples: hkBodySamples,
+ * });
+ * ```
+ */
+export class SomaHealthKit {
+  constructor(private component: SomaComponent) { }
+
+  // ─── Per-Type Sync Methods ─────────────────────────────────────────────
+
+  /**
+   * Sync workout activities from HealthKit.
+   *
+   * Transforms each `HKWorkout` into the Soma Activity schema and ingests it
+   * with automatic deduplication by `workout.uuid`.
+   *
+   * @param ctx - Mutation (or action) context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.workouts - Array of HKWorkout objects from HealthKit
+   */
+  async syncActivities(
+    ctx: MutationCtx,
+    args: { userId: string; workouts: HKWorkout[] },
+  ): Promise<SyncResult<{ activities: number }>> {
+    const connectionId = await this.resolveConnection(ctx, args.userId);
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    for (const workout of args.workouts) {
+      try {
+        const data = transformWorkout(workout);
+        await ctx.runMutation(this.component.public.ingestActivity, {
+          connectionId,
+          userId: args.userId,
+          ...data,
+        });
+        count++;
+      } catch (err) {
+        errors.push({
+          type: "activity",
+          id: workout.uuid,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    await this.updateLastDataUpdate(ctx, connectionId);
+    return { data: { synced: { activities: count } }, errors };
+  }
+
+  /**
+   * Sync sleep sessions from HealthKit.
+   *
+   * Each inner array represents one sleep session (all `HKCategorySample`
+   * stage records for a single night). Each session is aggregated into a
+   * single Soma Sleep document.
+   *
+   * @param ctx - Mutation (or action) context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.sessions - Array of sessions, each an array of sleep-stage samples
+   */
+  async syncSleep(
+    ctx: MutationCtx,
+    args: { userId: string; sessions: HKCategorySample[][] },
+  ): Promise<SyncResult<{ sleep: number }>> {
+    const connectionId = await this.resolveConnection(ctx, args.userId);
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    for (const session of args.sessions) {
+      const sessionId = session[0]?.uuid ?? "unknown";
+      try {
+        const data = transformSleep(session);
+        await ctx.runMutation(this.component.public.ingestSleep, {
+          connectionId,
+          userId: args.userId,
+          ...data,
+        });
+        count++;
+      } catch (err) {
+        errors.push({
+          type: "sleep",
+          id: sessionId,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    await this.updateLastDataUpdate(ctx, connectionId);
+    return { data: { synced: { sleep: count } }, errors };
+  }
+
+  /**
+   * Sync body metrics from HealthKit.
+   *
+   * Accepts a mixed array of body-related quantity samples (heart rate, HRV,
+   * blood pressure, SpO2, weight, etc.) for a single time window and produces
+   * one Soma Body document.
+   *
+   * @param ctx - Mutation (or action) context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.samples - Array of HKQuantitySample for the desired time range
+   * @param args.timeRange - Optional explicit time range; auto-detected from samples if omitted
+   */
+  async syncBody(
+    ctx: MutationCtx,
+    args: {
+      userId: string;
+      samples: HKQuantitySample[];
+      timeRange?: { start_time: string; end_time: string };
+    },
+  ): Promise<SyncResult<{ body: number }>> {
+    const connectionId = await this.resolveConnection(ctx, args.userId);
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformBody(args.samples, args.timeRange);
+      await ctx.runMutation(this.component.public.ingestBody, {
+        connectionId,
+        userId: args.userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "body",
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    await this.updateLastDataUpdate(ctx, connectionId);
+    return { data: { synced: { body: count } }, errors };
+  }
+
+  /**
+   * Sync daily activity data from HealthKit quantity samples.
+   *
+   * Accepts samples for a single day (steps, distance, energy, exercise time,
+   * heart rate, etc.) and produces one Soma Daily document.
+   *
+   * @param ctx - Mutation (or action) context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.samples - Array of HKQuantitySample for the desired day
+   * @param args.timeRange - Optional explicit time range; auto-detected from samples if omitted
+   */
+  async syncDaily(
+    ctx: MutationCtx,
+    args: {
+      userId: string;
+      samples: HKQuantitySample[];
+      timeRange?: { start_time: string; end_time: string };
+    },
+  ): Promise<SyncResult<{ daily: number }>> {
+    const connectionId = await this.resolveConnection(ctx, args.userId);
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformDaily(args.samples, args.timeRange);
+      await ctx.runMutation(this.component.public.ingestDaily, {
+        connectionId,
+        userId: args.userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "daily",
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    await this.updateLastDataUpdate(ctx, connectionId);
+    return { data: { synced: { daily: count } }, errors };
+  }
+
+  /**
+   * Sync daily activity data from HealthKit activity ring summaries.
+   *
+   * Each `HKActivitySummary` represents one day's activity rings (Move,
+   * Exercise, Stand). Each summary produces one Soma Daily document.
+   *
+   * @param ctx - Mutation (or action) context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.summaries - Array of HKActivitySummary from HealthKit
+   */
+  async syncDailyFromSummary(
+    ctx: MutationCtx,
+    args: { userId: string; summaries: HKActivitySummary[] },
+  ): Promise<SyncResult<{ daily: number }>> {
+    const connectionId = await this.resolveConnection(ctx, args.userId);
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    for (const summary of args.summaries) {
+      const { year, month, day } = summary.dateComponents;
+      const summaryId = `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+      try {
+        const data = transformDailyFromSummary(summary);
+        await ctx.runMutation(this.component.public.ingestDaily, {
+          connectionId,
+          userId: args.userId,
+          ...data,
+        });
+        count++;
+      } catch (err) {
+        errors.push({
+          type: "daily",
+          id: summaryId,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    await this.updateLastDataUpdate(ctx, connectionId);
+    return { data: { synced: { daily: count } }, errors };
+  }
+
+  /**
+   * Sync nutrition data from HealthKit.
+   *
+   * Accepts dietary quantity samples for a single time window and produces
+   * one Soma Nutrition document with macros and micros.
+   *
+   * @param ctx - Mutation (or action) context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.samples - Array of HKQuantitySample with dietary type identifiers
+   * @param args.timeRange - Optional explicit time range; auto-detected from samples if omitted
+   */
+  async syncNutrition(
+    ctx: MutationCtx,
+    args: {
+      userId: string;
+      samples: HKQuantitySample[];
+      timeRange?: { start_time: string; end_time: string };
+    },
+  ): Promise<SyncResult<{ nutrition: number }>> {
+    const connectionId = await this.resolveConnection(ctx, args.userId);
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformNutrition(args.samples, args.timeRange);
+      await ctx.runMutation(this.component.public.ingestNutrition, {
+        connectionId,
+        userId: args.userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "nutrition" as SomaError["type"],
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    await this.updateLastDataUpdate(ctx, connectionId);
+    return { data: { synced: { nutrition: count } }, errors };
+  }
+
+  /**
+   * Sync menstruation data from HealthKit.
+   *
+   * Accepts menstrual flow category samples for a single time window and
+   * produces one Soma Menstruation document.
+   *
+   * @param ctx - Mutation (or action) context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.samples - Array of HKCategorySample with menstrual flow values
+   * @param args.timeRange - Optional explicit time range; auto-detected from samples if omitted
+   */
+  async syncMenstruation(
+    ctx: MutationCtx,
+    args: {
+      userId: string;
+      samples: HKCategorySample[];
+      timeRange?: { start_time: string; end_time: string };
+    },
+  ): Promise<SyncResult<{ menstruation: number }>> {
+    const connectionId = await this.resolveConnection(ctx, args.userId);
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformMenstruation(args.samples, args.timeRange);
+      await ctx.runMutation(this.component.public.ingestMenstruation, {
+        connectionId,
+        userId: args.userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "menstruation",
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    await this.updateLastDataUpdate(ctx, connectionId);
+    return { data: { synced: { menstruation: count } }, errors };
+  }
+
+  /**
+   * Sync athlete profile from HealthKit.
+   *
+   * HealthKit exposes limited profile data (biological sex, date of birth).
+   * Produces one Soma Athlete document per connection.
+   *
+   * @param ctx - Mutation (or action) context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.characteristics - The HKCharacteristics from HealthKit
+   */
+  async syncAthlete(
+    ctx: MutationCtx,
+    args: { userId: string; characteristics: HKCharacteristics },
+  ): Promise<SyncResult<{ athletes: number }>> {
+    const connectionId = await this.resolveConnection(ctx, args.userId);
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformAthlete(args.characteristics);
+      await ctx.runMutation(this.component.public.ingestAthlete, {
+        connectionId,
+        userId: args.userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "athlete",
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    await this.updateLastDataUpdate(ctx, connectionId);
+    return { data: { synced: { athletes: count } }, errors };
+  }
+
+  // ─── Orchestrator ────────────────────────────────────────────────────────
+
+  /**
+   * Sync all provided HealthKit data types in a single call.
+   *
+   * Only data types with values provided are synced. Errors from individual
+   * data types are collected — one failing type does not block others.
+   *
+   * @param ctx - Mutation (or action) context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.workouts - Optional array of HKWorkout objects
+   * @param args.sleepSessions - Optional array of sleep sessions (each an array of stage samples)
+   * @param args.bodySamples - Optional body-related quantity samples
+   * @param args.dailySamples - Optional daily activity quantity samples
+   * @param args.dailySummaries - Optional daily activity ring summaries
+   * @param args.nutritionSamples - Optional dietary quantity samples
+   * @param args.menstruationSamples - Optional menstrual flow category samples
+   * @param args.characteristics - Optional user characteristics
+   *
+   * @example
+   * ```ts
+   * const result = await soma.healthkit.syncAll(ctx, {
+   *   userId: "user_123",
+   *   workouts: hkWorkouts,
+   *   sleepSessions: [nightSamples],
+   *   bodySamples: hkBodySamples,
+   *   dailySummaries: hkSummaries,
+   *   characteristics: hkCharacteristics,
+   * });
+   * ```
+   */
+  async syncAll(
+    ctx: MutationCtx,
+    args: {
+      userId: string;
+      workouts?: HKWorkout[];
+      sleepSessions?: HKCategorySample[][];
+      bodySamples?: HKQuantitySample[];
+      bodyTimeRange?: { start_time: string; end_time: string };
+      dailySamples?: HKQuantitySample[];
+      dailyTimeRange?: { start_time: string; end_time: string };
+      dailySummaries?: HKActivitySummary[];
+      nutritionSamples?: HKQuantitySample[];
+      nutritionTimeRange?: { start_time: string; end_time: string };
+      menstruationSamples?: HKCategorySample[];
+      menstruationTimeRange?: { start_time: string; end_time: string };
+      characteristics?: HKCharacteristics;
+    },
+  ): Promise<SyncResult<Record<string, number>>> {
+    // Resolve connection once, up front
+    const connectionId = await this.resolveConnection(ctx, args.userId);
+    const allErrors: SomaError[] = [];
+    const synced: Record<string, number> = {};
+
+    const run = async <T extends Record<string, number>>(
+      fn: () => Promise<SyncResult<T>>,
+      fallbackType: SomaError["type"],
+    ) => {
+      try {
+        const result = await fn();
+        Object.assign(synced, result.data.synced);
+        allErrors.push(...result.errors);
+      } catch (err) {
+        allErrors.push({
+          type: fallbackType,
+          id: "sync",
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    };
+
+    if (args.workouts) {
+      await run(
+        () => this.syncActivitiesInternal(ctx, connectionId, args.userId, args.workouts!),
+        "activity",
+      );
+    }
+    if (args.sleepSessions) {
+      await run(
+        () => this.syncSleepInternal(ctx, connectionId, args.userId, args.sleepSessions!),
+        "sleep",
+      );
+    }
+    if (args.bodySamples) {
+      await run(
+        () => this.syncBodyInternal(ctx, connectionId, args.userId, args.bodySamples!, args.bodyTimeRange),
+        "body",
+      );
+    }
+    if (args.dailySamples) {
+      await run(
+        () => this.syncDailyInternal(ctx, connectionId, args.userId, args.dailySamples!, args.dailyTimeRange),
+        "daily",
+      );
+    }
+    if (args.dailySummaries) {
+      await run(
+        () => this.syncDailyFromSummaryInternal(ctx, connectionId, args.userId, args.dailySummaries!),
+        "daily",
+      );
+    }
+    if (args.nutritionSamples) {
+      await run(
+        () => this.syncNutritionInternal(ctx, connectionId, args.userId, args.nutritionSamples!, args.nutritionTimeRange),
+        "nutrition" as SomaError["type"],
+      );
+    }
+    if (args.menstruationSamples) {
+      await run(
+        () => this.syncMenstruationInternal(ctx, connectionId, args.userId, args.menstruationSamples!, args.menstruationTimeRange),
+        "menstruation",
+      );
+    }
+    if (args.characteristics) {
+      await run(
+        () => this.syncAthleteInternal(ctx, connectionId, args.userId, args.characteristics!),
+        "athlete",
+      );
+    }
+
+    // Update lastDataUpdate once at the end
+    await this.updateLastDataUpdate(ctx, connectionId);
+
+    return { data: { synced }, errors: allErrors };
+  }
+
+  // ─── Private Helpers ───────────��─────────────────────────────────────────
+
+  /**
+   * Resolve or create the APPLE connection for a user.
+   *
+   * HealthKit permissions are managed on-device by the React Native library,
+   * so Soma auto-ensures the connection record exists. If the connection was
+   * previously disconnected it is re-activated automatically.
+   */
+  private async resolveConnection(
+    ctx: MutationCtx,
+    userId: string,
+  ): Promise<string> {
+    // `connect` is idempotent: creates if missing, re-activates if inactive.
+    return (await ctx.runMutation(this.component.public.connect, {
+      userId,
+      provider: PROVIDER,
+    })) as string;
+  }
+
+  private async updateLastDataUpdate(
+    ctx: MutationCtx,
+    connectionId: string,
+  ): Promise<void> {
+    await ctx.runMutation(this.component.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+  }
+
+  // ─── Internal sync methods (skip connection resolution + lastDataUpdate) ─
+
+  private async syncActivitiesInternal(
+    ctx: MutationCtx,
+    connectionId: string,
+    userId: string,
+    workouts: HKWorkout[],
+  ): Promise<SyncResult<{ activities: number }>> {
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    for (const workout of workouts) {
+      try {
+        const data = transformWorkout(workout);
+        await ctx.runMutation(this.component.public.ingestActivity, {
+          connectionId,
+          userId,
+          ...data,
+        });
+        count++;
+      } catch (err) {
+        errors.push({
+          type: "activity",
+          id: workout.uuid,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    return { data: { synced: { activities: count } }, errors };
+  }
+
+  private async syncSleepInternal(
+    ctx: MutationCtx,
+    connectionId: string,
+    userId: string,
+    sessions: HKCategorySample[][],
+  ): Promise<SyncResult<{ sleep: number }>> {
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    for (const session of sessions) {
+      const sessionId = session[0]?.uuid ?? "unknown";
+      try {
+        const data = transformSleep(session);
+        await ctx.runMutation(this.component.public.ingestSleep, {
+          connectionId,
+          userId,
+          ...data,
+        });
+        count++;
+      } catch (err) {
+        errors.push({
+          type: "sleep",
+          id: sessionId,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    return { data: { synced: { sleep: count } }, errors };
+  }
+
+  private async syncBodyInternal(
+    ctx: MutationCtx,
+    connectionId: string,
+    userId: string,
+    samples: HKQuantitySample[],
+    timeRange?: { start_time: string; end_time: string },
+  ): Promise<SyncResult<{ body: number }>> {
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformBody(samples, timeRange);
+      await ctx.runMutation(this.component.public.ingestBody, {
+        connectionId,
+        userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "body",
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    return { data: { synced: { body: count } }, errors };
+  }
+
+  private async syncDailyInternal(
+    ctx: MutationCtx,
+    connectionId: string,
+    userId: string,
+    samples: HKQuantitySample[],
+    timeRange?: { start_time: string; end_time: string },
+  ): Promise<SyncResult<{ daily: number }>> {
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformDaily(samples, timeRange);
+      await ctx.runMutation(this.component.public.ingestDaily, {
+        connectionId,
+        userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "daily",
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    return { data: { synced: { daily: count } }, errors };
+  }
+
+  private async syncDailyFromSummaryInternal(
+    ctx: MutationCtx,
+    connectionId: string,
+    userId: string,
+    summaries: HKActivitySummary[],
+  ): Promise<SyncResult<{ daily: number }>> {
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    for (const summary of summaries) {
+      const { year, month, day } = summary.dateComponents;
+      const summaryId = `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
+      try {
+        const data = transformDailyFromSummary(summary);
+        await ctx.runMutation(this.component.public.ingestDaily, {
+          connectionId,
+          userId,
+          ...data,
+        });
+        count++;
+      } catch (err) {
+        errors.push({
+          type: "daily",
+          id: summaryId,
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    return { data: { synced: { daily: count } }, errors };
+  }
+
+  private async syncNutritionInternal(
+    ctx: MutationCtx,
+    connectionId: string,
+    userId: string,
+    samples: HKQuantitySample[],
+    timeRange?: { start_time: string; end_time: string },
+  ): Promise<SyncResult<{ nutrition: number }>> {
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformNutrition(samples, timeRange);
+      await ctx.runMutation(this.component.public.ingestNutrition, {
+        connectionId,
+        userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "nutrition" as SomaError["type"],
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    return { data: { synced: { nutrition: count } }, errors };
+  }
+
+  private async syncMenstruationInternal(
+    ctx: MutationCtx,
+    connectionId: string,
+    userId: string,
+    samples: HKCategorySample[],
+    timeRange?: { start_time: string; end_time: string },
+  ): Promise<SyncResult<{ menstruation: number }>> {
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformMenstruation(samples, timeRange);
+      await ctx.runMutation(this.component.public.ingestMenstruation, {
+        connectionId,
+        userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "menstruation",
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    return { data: { synced: { menstruation: count } }, errors };
+  }
+
+  private async syncAthleteInternal(
+    ctx: MutationCtx,
+    connectionId: string,
+    userId: string,
+    characteristics: HKCharacteristics,
+  ): Promise<SyncResult<{ athletes: number }>> {
+    const errors: SomaError[] = [];
+    let count = 0;
+
+    try {
+      const data = transformAthlete(characteristics);
+      await ctx.runMutation(this.component.public.ingestAthlete, {
+        connectionId,
+        userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "athlete",
+        id: "transform",
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+
+    return { data: { synced: { athletes: count } }, errors };
+  }
+}