@nativesquare/soma 0.16.1 → 0.16.3

package/src/client/healthkit.ts

@@ -1,791 +1,283 @@
-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 };
-  }
-}
+import type { SomaComponent } from "./index.js";
+import type { MutationCtx, SomaError, SomaResult } from "./types.js";
+import type {
+  HKWorkout,
+  HKCategorySample,
+  HKQuantitySample,
+  HKActivitySummary,
+  HKCharacteristics,
+} from "../component/healthkit/types.js";
+
+/**
+ * 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 is a thin wrapper over the component's public
+ * mutations, which own the transform + ingest pipeline.
+ *
+ * Because HealthKit permissions are managed in iOS Settings, the server
+ * cannot independently verify whether the user has granted or revoked
+ * access. The `connect()` / `disconnect()` methods therefore represent
+ * assertions by the host app about the state it has observed on-device:
+ *
+ * - Call {@link SomaHealthKit.connect | connect} once the React Native
+ *   HealthKit library confirms permissions were granted.
+ * - Call {@link SomaHealthKit.disconnect | disconnect} when the user
+ *   turns HealthKit off in your app's settings, or when you otherwise
+ *   detect that syncs are no longer returning data.
+ *
+ * Sync methods refuse to run unless an active connection exists.
+ *
+ * @example
+ * ```ts
+ * // Once, after the RN library confirms permissions:
+ * await soma.healthkit.connect(ctx, { userId: "user_123" });
+ *
+ * // Sync workouts received from the React Native client:
+ * const result = await soma.healthkit.syncActivities(ctx, {
+ *   userId: "user_123",
+ *   workouts: hkWorkouts,
+ * });
+ * // result: { data: { activities: 5 }, errors: [] }
+ *
+ * // Or sync everything at once:
+ * await soma.healthkit.syncAll(ctx, {
+ *   userId: "user_123",
+ *   workouts: hkWorkouts,
+ *   sleepSessions: [nightSamples],
+ *   bodySamples: hkBodySamples,
+ * });
+ *
+ * // When the user disables HealthKit in your app:
+ * await soma.healthkit.disconnect(ctx, { userId: "user_123" });
+ * ```
+ */
+export class SomaHealthKit {
+  constructor(private component: SomaComponent) { }
+
+  // ─── Connect / Disconnect ──────────────────────────────────────────────
+
+  /**
+   * Assert that HealthKit is connected for this user.
+   *
+   * Call this once after the React Native HealthKit library confirms
+   * permissions were granted. Creates the APPLE connection if missing,
+   * or re-activates it if previously disconnected. Idempotent.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args.userId - The host app's user identifier
+   * @returns The connection document ID
+   */
+  async connect(
+    ctx: MutationCtx,
+    args: { userId: string },
+  ): Promise<string> {
+    return await ctx.runMutation(this.component.healthkit.public.connect, args);
+  }
+
+  /**
+   * Mark the HealthKit connection inactive for this user.
+   *
+   * Call this when the user disables HealthKit in your app's settings, or
+   * when you detect that sync calls are no longer returning data (suggesting
+   * the user revoked permissions in iOS Settings). Subsequent sync methods
+   * will throw until {@link SomaHealthKit.connect | connect} is called again.
+   *
+   * Does not delete the connection row or any previously synced data —
+   * re-connecting later preserves history.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args.userId - The host app's user identifier
+   */
+  async disconnect(
+    ctx: MutationCtx,
+    args: { userId: string },
+  ): Promise<null> {
+    return await ctx.runMutation(this.component.healthkit.public.disconnect, args);
+  }
+
+  // ─── 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`.
+   */
+  async syncActivities(
+    ctx: MutationCtx,
+    args: { userId: string; workouts: HKWorkout[] },
+  ): Promise<SomaResult<{ activities: number }>> {
+    return (await ctx.runMutation(
+      this.component.healthkit.public.syncActivities,
+      args,
+    )) as SomaResult<{ activities: number }>;
+  }
+
+  /**
+   * 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.
+   */
+  async syncSleep(
+    ctx: MutationCtx,
+    args: { userId: string; sessions: HKCategorySample[][] },
+  ): Promise<SomaResult<{ sleep: number }>> {
+    return (await ctx.runMutation(
+      this.component.healthkit.public.syncSleep,
+      args,
+    )) as SomaResult<{ sleep: number }>;
+  }
+
+  /**
+   * 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.
+   */
+  async syncBody(
+    ctx: MutationCtx,
+    args: {
+      userId: string;
+      samples: HKQuantitySample[];
+      timeRange?: { start_time: string; end_time: string };
+    },
+  ): Promise<SomaResult<{ body: number }>> {
+    return (await ctx.runMutation(
+      this.component.healthkit.public.syncBody,
+      args,
+    )) as SomaResult<{ body: number }>;
+  }
+
+  /**
+   * Sync daily activity data from HealthKit quantity samples.
+   */
+  async syncDaily(
+    ctx: MutationCtx,
+    args: {
+      userId: string;
+      samples: HKQuantitySample[];
+      timeRange?: { start_time: string; end_time: string };
+    },
+  ): Promise<SomaResult<{ daily: number }>> {
+    return (await ctx.runMutation(
+      this.component.healthkit.public.syncDaily,
+      args,
+    )) as SomaResult<{ daily: number }>;
+  }
+
+  /**
+   * Sync daily activity data from HealthKit activity ring summaries.
+   */
+  async syncDailyFromSummary(
+    ctx: MutationCtx,
+    args: { userId: string; summaries: HKActivitySummary[] },
+  ): Promise<SomaResult<{ daily: number }>> {
+    return (await ctx.runMutation(
+      this.component.healthkit.public.syncDailyFromSummary,
+      args,
+    )) as SomaResult<{ daily: number }>;
+  }
+
+  /**
+   * Sync nutrition data from HealthKit.
+   */
+  async syncNutrition(
+    ctx: MutationCtx,
+    args: {
+      userId: string;
+      samples: HKQuantitySample[];
+      timeRange?: { start_time: string; end_time: string };
+    },
+  ): Promise<SomaResult<{ nutrition: number }>> {
+    return (await ctx.runMutation(
+      this.component.healthkit.public.syncNutrition,
+      args,
+    )) as SomaResult<{ nutrition: number }>;
+  }
+
+  /**
+   * Sync menstruation data from HealthKit.
+   */
+  async syncMenstruation(
+    ctx: MutationCtx,
+    args: {
+      userId: string;
+      samples: HKCategorySample[];
+      timeRange?: { start_time: string; end_time: string };
+    },
+  ): Promise<SomaResult<{ menstruation: number }>> {
+    return (await ctx.runMutation(
+      this.component.healthkit.public.syncMenstruation,
+      args,
+    )) as SomaResult<{ menstruation: number }>;
+  }
+
+  /**
+   * Sync athlete profile from HealthKit.
+   *
+   * HealthKit exposes limited profile data (biological sex, date of birth).
+   * Produces one Soma Athlete document per connection.
+   */
+  async syncAthlete(
+    ctx: MutationCtx,
+    args: { userId: string; characteristics: HKCharacteristics },
+  ): Promise<SomaResult<{ athletes: number }>> {
+    return (await ctx.runMutation(
+      this.component.healthkit.public.syncAthlete,
+      args,
+    )) as SomaResult<{ athletes: number }>;
+  }
+
+  // ─── 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.
+   *
+   * @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<SomaResult<Record<string, number>>> {
+    return (await ctx.runMutation(
+      this.component.healthkit.public.syncAll,
+      args,
+    )) as SomaResult<Record<string, number>>;
+  }
+}
+
+// Re-export for JSDoc link resolution above.
+export type { SomaError };