@nativesquare/soma 0.16.2 → 0.16.4

package/src/component/healthkit/public.ts

@@ -0,0 +1,597 @@
+// ─── HealthKit Public Mutations ──────────────────────────────────────────────
+// Per-data-type sync mutations plus connect/disconnect, called by the host app
+// through the SomaHealthKit client class. Because HealthKit is an on-device
+// provider, these are `mutation` (not `action`) — all data is supplied by the
+// caller, nothing is fetched from an external API.
+
+import { v } from "convex/values";
+import { mutation } from "../_generated/server.js";
+import type { MutationCtx } from "../_generated/server.js";
+import type { Id } from "../_generated/dataModel.js";
+import { api } from "../_generated/api.js";
+import type { SomaError } from "../validators/shared.js";
+import { transformWorkout } from "./transform/activity.js";
+import { transformSleep } from "./transform/sleep.js";
+import { transformBody } from "./transform/body.js";
+import {
+  transformDaily,
+  transformDailyFromSummary,
+} from "./transform/daily.js";
+import { transformNutrition } from "./transform/nutrition.js";
+import { transformMenstruation } from "./transform/menstruation.js";
+import { transformAthlete } from "./transform/athlete.js";
+import type {
+  HKWorkout,
+  HKCategorySample,
+  HKQuantitySample,
+  HKActivitySummary,
+  HKCharacteristics,
+} from "./types.js";
+import {
+  syncActivitiesArgs,
+  syncSleepArgs,
+  syncBodyArgs,
+  syncDailyArgs,
+  syncDailyFromSummaryArgs,
+  syncNutritionArgs,
+  syncMenstruationArgs,
+  syncAthleteArgs,
+  syncAllHealthKitArgs,
+  syncActivitiesReturn,
+  syncSleepReturn,
+  syncBodyReturn,
+  syncDailyReturn,
+  syncNutritionReturn,
+  syncMenstruationReturn,
+  syncAthleteReturn,
+  syncAllReturn,
+} from "./validators.js";
+
+const PROVIDER = "HEALTHKIT";
+
+// ─── Internal helpers ───────────────────────────────────────────────────────
+
+/**
+ * Load the active HEALTHKIT connection for a user, or throw if missing/inactive.
+ *
+ * HealthKit permissions are managed on-device, so the connection state is an
+ * assertion made by the host via {@link connect} / {@link disconnect}. Sync
+ * mutations refuse to run without an active connection.
+ */
+async function requireActiveConnection(
+  ctx: MutationCtx,
+  userId: string,
+): Promise<Id<"connections">> {
+  const connection = await ctx.db
+    .query("connections")
+    .withIndex("by_userId_provider", (q) =>
+      q.eq("userId", userId).eq("provider", PROVIDER),
+    )
+    .first();
+  if (!connection) {
+    throw new Error(
+      `No HealthKit connection for user "${userId}". Call soma.healthkit.connect(ctx, { userId }) after the React Native HealthKit library confirms permissions.`,
+    );
+  }
+  if (connection.active === false) {
+    throw new Error(
+      `HealthKit connection for user "${userId}" is disconnected. Call soma.healthkit.connect(ctx, { userId }) to re-activate.`,
+    );
+  }
+  return connection._id;
+}
+
+async function touchLastDataUpdate(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+): Promise<void> {
+  await ctx.runMutation(api.public.updateConnection, {
+    connectionId,
+    lastDataUpdate: new Date().toISOString(),
+  });
+}
+
+// ─── Per-type processors (no connection resolution, no lastDataUpdate) ──────
+
+async function processActivities(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+  userId: string,
+  workouts: HKWorkout[],
+): Promise<{ count: number; errors: SomaError[] }> {
+  const errors: SomaError[] = [];
+  let count = 0;
+  for (const workout of workouts) {
+    try {
+      const data = transformWorkout(workout);
+      await ctx.runMutation(api.public.ingestActivity, {
+        connectionId,
+        userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "activity",
+        id: workout.uuid,
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  return { count, errors };
+}
+
+async function processSleep(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+  userId: string,
+  sessions: HKCategorySample[][],
+): Promise<{ count: number; errors: SomaError[] }> {
+  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(api.public.ingestSleep, {
+        connectionId,
+        userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "sleep",
+        id: sessionId,
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  return { count, errors };
+}
+
+async function processBody(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+  userId: string,
+  samples: HKQuantitySample[],
+  timeRange?: { start_time: string; end_time: string },
+): Promise<{ count: number; errors: SomaError[] }> {
+  const errors: SomaError[] = [];
+  let count = 0;
+  try {
+    const data = transformBody(samples, timeRange);
+    await ctx.runMutation(api.public.ingestBody, {
+      connectionId,
+      userId,
+      ...data,
+    });
+    count++;
+  } catch (err) {
+    errors.push({
+      type: "body",
+      id: "transform",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+  return { count, errors };
+}
+
+async function processDaily(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+  userId: string,
+  samples: HKQuantitySample[],
+  timeRange?: { start_time: string; end_time: string },
+): Promise<{ count: number; errors: SomaError[] }> {
+  const errors: SomaError[] = [];
+  let count = 0;
+  try {
+    const data = transformDaily(samples, timeRange);
+    await ctx.runMutation(api.public.ingestDaily, {
+      connectionId,
+      userId,
+      ...data,
+    });
+    count++;
+  } catch (err) {
+    errors.push({
+      type: "daily",
+      id: "transform",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+  return { count, errors };
+}
+
+async function processDailyFromSummary(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+  userId: string,
+  summaries: HKActivitySummary[],
+): Promise<{ count: number; errors: SomaError[] }> {
+  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(api.public.ingestDaily, {
+        connectionId,
+        userId,
+        ...data,
+      });
+      count++;
+    } catch (err) {
+      errors.push({
+        type: "daily",
+        id: summaryId,
+        message: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+  return { count, errors };
+}
+
+async function processNutrition(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+  userId: string,
+  samples: HKQuantitySample[],
+  timeRange?: { start_time: string; end_time: string },
+): Promise<{ count: number; errors: SomaError[] }> {
+  const errors: SomaError[] = [];
+  let count = 0;
+  try {
+    const data = transformNutrition(samples, timeRange);
+    await ctx.runMutation(api.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 { count, errors };
+}
+
+async function processMenstruation(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+  userId: string,
+  samples: HKCategorySample[],
+  timeRange?: { start_time: string; end_time: string },
+): Promise<{ count: number; errors: SomaError[] }> {
+  const errors: SomaError[] = [];
+  let count = 0;
+  try {
+    const data = transformMenstruation(samples, timeRange);
+    await ctx.runMutation(api.public.ingestMenstruation, {
+      connectionId,
+      userId,
+      ...data,
+    });
+    count++;
+  } catch (err) {
+    errors.push({
+      type: "menstruation",
+      id: "transform",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+  return { count, errors };
+}
+
+async function processAthlete(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+  userId: string,
+  characteristics: HKCharacteristics,
+): Promise<{ count: number; errors: SomaError[] }> {
+  const errors: SomaError[] = [];
+  let count = 0;
+  try {
+    const data = transformAthlete(characteristics);
+    await ctx.runMutation(api.public.ingestAthlete, {
+      connectionId,
+      userId,
+      ...data,
+    });
+    count++;
+  } catch (err) {
+    errors.push({
+      type: "athlete",
+      id: "transform",
+      message: err instanceof Error ? err.message : String(err),
+    });
+  }
+  return { count, errors };
+}
+
+// ─── Connect / Disconnect ────────────────────────────────────────────────────
+
+/**
+ * Assert that HealthKit is connected for this user. Creates the HEALTHKIT
+ * connection if missing or re-activates it if previously disconnected.
+ * Idempotent.
+ */
+export const connect = mutation({
+  args: {
+    userId: v.string(),
+  },
+  returns: v.id("connections"),
+  handler: async (ctx, args): Promise<Id<"connections">> => {
+    return await ctx.runMutation(api.public.connect, {
+      userId: args.userId,
+      provider: PROVIDER,
+    });
+  },
+});
+
+/**
+ * Mark the HealthKit connection inactive for this user. Does not delete
+ * the connection row or any previously synced data.
+ */
+export const disconnect = mutation({
+  args: {
+    userId: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.runMutation(api.public.disconnect, {
+      userId: args.userId,
+      provider: PROVIDER,
+    });
+    return null;
+  },
+});
+
+// ─── Per-type sync mutations ─────────────────────────────────────────────────
+
+export const syncActivities = mutation({
+  args: syncActivitiesArgs,
+  returns: syncActivitiesReturn,
+  handler: async (ctx, args) => {
+    const connectionId = await requireActiveConnection(ctx, args.userId);
+    const { count, errors } = await processActivities(
+      ctx,
+      connectionId,
+      args.userId,
+      args.workouts,
+    );
+    await touchLastDataUpdate(ctx, connectionId);
+    return { data: { activities: count }, errors };
+  },
+});
+
+export const syncSleep = mutation({
+  args: syncSleepArgs,
+  returns: syncSleepReturn,
+  handler: async (ctx, args) => {
+    const connectionId = await requireActiveConnection(ctx, args.userId);
+    const { count, errors } = await processSleep(
+      ctx,
+      connectionId,
+      args.userId,
+      args.sessions,
+    );
+    await touchLastDataUpdate(ctx, connectionId);
+    return { data: { sleep: count }, errors };
+  },
+});
+
+export const syncBody = mutation({
+  args: syncBodyArgs,
+  returns: syncBodyReturn,
+  handler: async (ctx, args) => {
+    const connectionId = await requireActiveConnection(ctx, args.userId);
+    const { count, errors } = await processBody(
+      ctx,
+      connectionId,
+      args.userId,
+      args.samples,
+      args.timeRange,
+    );
+    await touchLastDataUpdate(ctx, connectionId);
+    return { data: { body: count }, errors };
+  },
+});
+
+export const syncDaily = mutation({
+  args: syncDailyArgs,
+  returns: syncDailyReturn,
+  handler: async (ctx, args) => {
+    const connectionId = await requireActiveConnection(ctx, args.userId);
+    const { count, errors } = await processDaily(
+      ctx,
+      connectionId,
+      args.userId,
+      args.samples,
+      args.timeRange,
+    );
+    await touchLastDataUpdate(ctx, connectionId);
+    return { data: { daily: count }, errors };
+  },
+});
+
+export const syncDailyFromSummary = mutation({
+  args: syncDailyFromSummaryArgs,
+  returns: syncDailyReturn,
+  handler: async (ctx, args) => {
+    const connectionId = await requireActiveConnection(ctx, args.userId);
+    const { count, errors } = await processDailyFromSummary(
+      ctx,
+      connectionId,
+      args.userId,
+      args.summaries,
+    );
+    await touchLastDataUpdate(ctx, connectionId);
+    return { data: { daily: count }, errors };
+  },
+});
+
+export const syncNutrition = mutation({
+  args: syncNutritionArgs,
+  returns: syncNutritionReturn,
+  handler: async (ctx, args) => {
+    const connectionId = await requireActiveConnection(ctx, args.userId);
+    const { count, errors } = await processNutrition(
+      ctx,
+      connectionId,
+      args.userId,
+      args.samples,
+      args.timeRange,
+    );
+    await touchLastDataUpdate(ctx, connectionId);
+    return { data: { nutrition: count }, errors };
+  },
+});
+
+export const syncMenstruation = mutation({
+  args: syncMenstruationArgs,
+  returns: syncMenstruationReturn,
+  handler: async (ctx, args) => {
+    const connectionId = await requireActiveConnection(ctx, args.userId);
+    const { count, errors } = await processMenstruation(
+      ctx,
+      connectionId,
+      args.userId,
+      args.samples,
+      args.timeRange,
+    );
+    await touchLastDataUpdate(ctx, connectionId);
+    return { data: { menstruation: count }, errors };
+  },
+});
+
+export const syncAthlete = mutation({
+  args: syncAthleteArgs,
+  returns: syncAthleteReturn,
+  handler: async (ctx, args) => {
+    const connectionId = await requireActiveConnection(ctx, args.userId);
+    const { count, errors } = await processAthlete(
+      ctx,
+      connectionId,
+      args.userId,
+      args.characteristics,
+    );
+    await touchLastDataUpdate(ctx, connectionId);
+    return { data: { athletes: count }, errors };
+  },
+});
+
+// ─── Orchestrator ────────────────────────────────────────────────────────────
+
+/**
+ * Sync all provided HealthKit data types in a single transaction.
+ *
+ * Only types with values provided are synced. Errors from individual data
+ * types are collected — one failing type does not block others. The
+ * connection is resolved once and `lastDataUpdate` is written once.
+ */
+export const syncAll = mutation({
+  args: syncAllHealthKitArgs,
+  returns: syncAllReturn,
+  handler: async (ctx, args) => {
+    const connectionId = await requireActiveConnection(ctx, args.userId);
+    const allErrors: SomaError[] = [];
+    const counts: Record<string, number> = {};
+
+    const record = (key: string, result: { count: number; errors: SomaError[] }) => {
+      counts[key] = (counts[key] ?? 0) + result.count;
+      allErrors.push(...result.errors);
+    };
+
+    if (args.workouts) {
+      record(
+        "activities",
+        await processActivities(ctx, connectionId, args.userId, args.workouts),
+      );
+    }
+    if (args.sleepSessions) {
+      record(
+        "sleep",
+        await processSleep(ctx, connectionId, args.userId, args.sleepSessions),
+      );
+    }
+    if (args.bodySamples) {
+      record(
+        "body",
+        await processBody(
+          ctx,
+          connectionId,
+          args.userId,
+          args.bodySamples,
+          args.bodyTimeRange,
+        ),
+      );
+    }
+    if (args.dailySamples) {
+      record(
+        "daily",
+        await processDaily(
+          ctx,
+          connectionId,
+          args.userId,
+          args.dailySamples,
+          args.dailyTimeRange,
+        ),
+      );
+    }
+    if (args.dailySummaries) {
+      record(
+        "daily",
+        await processDailyFromSummary(
+          ctx,
+          connectionId,
+          args.userId,
+          args.dailySummaries,
+        ),
+      );
+    }
+    if (args.nutritionSamples) {
+      record(
+        "nutrition",
+        await processNutrition(
+          ctx,
+          connectionId,
+          args.userId,
+          args.nutritionSamples,
+          args.nutritionTimeRange,
+        ),
+      );
+    }
+    if (args.menstruationSamples) {
+      record(
+        "menstruation",
+        await processMenstruation(
+          ctx,
+          connectionId,
+          args.userId,
+          args.menstruationSamples,
+          args.menstruationTimeRange,
+        ),
+      );
+    }
+    if (args.characteristics) {
+      record(
+        "athletes",
+        await processAthlete(
+          ctx,
+          connectionId,
+          args.userId,
+          args.characteristics,
+        ),
+      );
+    }
+
+    await touchLastDataUpdate(ctx, connectionId);
+    return { data: counts, errors: allErrors };
+  },
+});