@nativesquare/soma 0.16.1 → 0.16.3

package/dist/client/healthkit.js

@@ -1,30 +1,36 @@
-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";
 /**
  * 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.
+ * cloud API. This class is a thin wrapper over the component's public
+ * mutations, which own the transform + ingest pipeline.
  *
- * No configuration is required — HealthKit has no OAuth credentials.
+ * 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: { synced: { activities: 5 } }, errors: [] }
+ * // result: { data: { activities: 5 }, errors: [] }
  *
  * // Or sync everything at once:
  * await soma.healthkit.syncAll(ctx, {
@@ -33,6 +39,9 @@ const PROVIDER = "APPLE";
  *   sleepSessions: [nightSamples],
  *   bodySamples: hkBodySamples,
  * });
+ *
+ * // When the user disables HealthKit in your app:
+ * await soma.healthkit.disconnect(ctx, { userId: "user_123" });
  * ```
  */
 export class SomaHealthKit {
@@ -40,41 +49,47 @@ export class SomaHealthKit {
     constructor(component) {
         this.component = component;
     }
+    // ─── 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, args) {
+        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, args) {
+        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`.
-     *
-     * @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, args) {
-        const connectionId = await this.resolveConnection(ctx, args.userId);
-        const errors = [];
-        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 };
+        return (await ctx.runMutation(this.component.healthkit.public.syncActivities, args));
     }
     /**
      * Sync sleep sessions from HealthKit.
@@ -82,36 +97,9 @@ export class SomaHealthKit {
      * 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, args) {
-        const connectionId = await this.resolveConnection(ctx, args.userId);
-        const errors = [];
-        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 };
+        return (await ctx.runMutation(this.component.healthkit.public.syncSleep, args));
     }
     /**
      * Sync body metrics from HealthKit.
@@ -119,206 +107,42 @@ export class SomaHealthKit {
      * 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, args) {
-        const connectionId = await this.resolveConnection(ctx, args.userId);
-        const errors = [];
-        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 };
+        return (await ctx.runMutation(this.component.healthkit.public.syncBody, args));
     }
     /**
      * 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, args) {
-        const connectionId = await this.resolveConnection(ctx, args.userId);
-        const errors = [];
-        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 };
+        return (await ctx.runMutation(this.component.healthkit.public.syncDaily, args));
     }
     /**
      * 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, args) {
-        const connectionId = await this.resolveConnection(ctx, args.userId);
-        const errors = [];
-        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 };
+        return (await ctx.runMutation(this.component.healthkit.public.syncDailyFromSummary, args));
     }
     /**
      * 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, args) {
-        const connectionId = await this.resolveConnection(ctx, args.userId);
-        const errors = [];
-        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",
-                id: "transform",
-                message: err instanceof Error ? err.message : String(err),
-            });
-        }
-        await this.updateLastDataUpdate(ctx, connectionId);
-        return { data: { synced: { nutrition: count } }, errors };
+        return (await ctx.runMutation(this.component.healthkit.public.syncNutrition, args));
     }
     /**
      * 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, args) {
-        const connectionId = await this.resolveConnection(ctx, args.userId);
-        const errors = [];
-        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 };
+        return (await ctx.runMutation(this.component.healthkit.public.syncMenstruation, args));
     }
     /**
      * 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, args) {
-        const connectionId = await this.resolveConnection(ctx, args.userId);
-        const errors = [];
-        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 };
+        return (await ctx.runMutation(this.component.healthkit.public.syncAthlete, args));
     }
     // ─── Orchestrator ────────────────────────────────────────────────────────
     /**
@@ -327,17 +151,6 @@ export class SomaHealthKit {
      * 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, {
@@ -351,250 +164,7 @@ export class SomaHealthKit {
      * ```
      */
     async syncAll(ctx, args) {
-        // Resolve connection once, up front
-        const connectionId = await this.resolveConnection(ctx, args.userId);
-        const allErrors = [];
-        const synced = {};
-        const run = async (fn, fallbackType) => {
-            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");
-        }
-        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.
-     */
-    async resolveConnection(ctx, userId) {
-        // `connect` is idempotent: creates if missing, re-activates if inactive.
-        return (await ctx.runMutation(this.component.public.connect, {
-            userId,
-            provider: PROVIDER,
-        }));
-    }
-    async updateLastDataUpdate(ctx, connectionId) {
-        await ctx.runMutation(this.component.public.updateConnection, {
-            connectionId,
-            lastDataUpdate: new Date().toISOString(),
-        });
-    }
-    // ─── Internal sync methods (skip connection resolution + lastDataUpdate) ─
-    async syncActivitiesInternal(ctx, connectionId, userId, workouts) {
-        const errors = [];
-        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 };
-    }
-    async syncSleepInternal(ctx, connectionId, userId, sessions) {
-        const errors = [];
-        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 };
-    }
-    async syncBodyInternal(ctx, connectionId, userId, samples, timeRange) {
-        const errors = [];
-        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 };
-    }
-    async syncDailyInternal(ctx, connectionId, userId, samples, timeRange) {
-        const errors = [];
-        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 };
-    }
-    async syncDailyFromSummaryInternal(ctx, connectionId, userId, summaries) {
-        const errors = [];
-        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 };
-    }
-    async syncNutritionInternal(ctx, connectionId, userId, samples, timeRange) {
-        const errors = [];
-        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",
-                id: "transform",
-                message: err instanceof Error ? err.message : String(err),
-            });
-        }
-        return { data: { synced: { nutrition: count } }, errors };
-    }
-    async syncMenstruationInternal(ctx, connectionId, userId, samples, timeRange) {
-        const errors = [];
-        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 };
-    }
-    async syncAthleteInternal(ctx, connectionId, userId, characteristics) {
-        const errors = [];
-        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 };
+        return (await ctx.runMutation(this.component.healthkit.public.syncAll, args));
     }
 }
 //# sourceMappingURL=healthkit.js.map