@nativesquare/soma 0.14.0 → 0.16.0

package/src/client/index.ts

@@ -12,6 +12,7 @@ import type {
 export type {
   ActionCtx,
   SomaError,
+  SomaErrorType,
   SomaResult,
   SomaStravaConfig,
   SomaGarminConfig,
@@ -40,9 +41,11 @@ export type {
 } from "./types.js";
 import type { HttpRouter } from "convex/server";
 import { SomaGarmin } from "./garmin.js";
+import { SomaHealthKit } from "./healthkit.js";
 import { SomaStrava } from "./strava.js";
 
 export { SomaGarmin } from "./garmin.js";
+export { SomaHealthKit } from "./healthkit.js";
 export { SomaStrava } from "./strava.js";
 export { STRAVA_OAUTH_CALLBACK_PATH, STRAVA_WEBHOOK_BASE_PATH } from "./strava.js";
 export { GARMIN_OAUTH_CALLBACK_PATH, GARMIN_WEBHOOK_BASE_PATH } from "./garmin.js";
@@ -90,6 +93,7 @@ export class Soma {
   private garminConfig?: SomaGarminConfig;
 
   public readonly garmin: SomaGarmin;
+  public readonly healthkit: SomaHealthKit;
   public readonly strava: SomaStrava;
 
   constructor(
@@ -100,6 +104,7 @@ export class Soma {
     this.garminConfig = options?.garmin ?? this.readGarminEnv();
 
     this.garmin = new SomaGarmin(this.component, () => this.requireGarminConfig());
+    this.healthkit = new SomaHealthKit(this.component);
     this.strava = new SomaStrava(this.component, () => this.requireStravaConfig());
   }
 

package/src/client/types.ts

@@ -53,6 +53,8 @@ export interface SomaGarminConfig {
 
 // ─── Shared Error & Result Types ───────────────────────────────────────────
 
+export type { SomaErrorType } from "../component/validators/shared.js";
+
 /**
  * A structured error from a Soma operation.
  *
@@ -61,8 +63,8 @@ export interface SomaGarminConfig {
  * (missing connection, nonexistent document) are thrown as exceptions.
  */
 export interface SomaError {
-  /** Category of the failed item (e.g. `"activity"`, `"pushWorkout"`, `"ingest"`). */
-  type: string;
+  /** Category of the failed item — see {@link SomaErrorType} for valid values. */
+  type: import("../component/validators/shared.js").SomaErrorType;
   /** Identifier of the failed item, or `"fetch"` for API-level failures. */
   id: string;
   /** Human-readable error description. */

package/src/component/_generated/api.ts

@@ -55,6 +55,19 @@ import type * as garmin_types_wellnessApi_client_index from "../garmin/types/wel
 import type * as garmin_types_wellnessApi_index from "../garmin/types/wellnessApi/index.js";
 import type * as garmin_utils from "../garmin/utils.js";
 import type * as garmin_webhooks from "../garmin/webhooks.js";
+import type * as healthkit_index from "../healthkit/index.js";
+import type * as healthkit_transform_activity from "../healthkit/transform/activity.js";
+import type * as healthkit_transform_athlete from "../healthkit/transform/athlete.js";
+import type * as healthkit_transform_body from "../healthkit/transform/body.js";
+import type * as healthkit_transform_daily from "../healthkit/transform/daily.js";
+import type * as healthkit_transform_maps_activityType from "../healthkit/transform/maps/activityType.js";
+import type * as healthkit_transform_maps_menstruationFlow from "../healthkit/transform/maps/menstruationFlow.js";
+import type * as healthkit_transform_maps_sleepLevel from "../healthkit/transform/maps/sleepLevel.js";
+import type * as healthkit_transform_menstruation from "../healthkit/transform/menstruation.js";
+import type * as healthkit_transform_nutrition from "../healthkit/transform/nutrition.js";
+import type * as healthkit_transform_sleep from "../healthkit/transform/sleep.js";
+import type * as healthkit_transform_utils from "../healthkit/transform/utils.js";
+import type * as healthkit_types from "../healthkit/types.js";
 import type * as private_ from "../private.js";
 import type * as public_ from "../public.js";
 import type * as strava_auth from "../strava/auth.js";
@@ -137,6 +150,19 @@ const fullApi: ApiFromModules<{
   "garmin/types/wellnessApi/index": typeof garmin_types_wellnessApi_index;
   "garmin/utils": typeof garmin_utils;
   "garmin/webhooks": typeof garmin_webhooks;
+  "healthkit/index": typeof healthkit_index;
+  "healthkit/transform/activity": typeof healthkit_transform_activity;
+  "healthkit/transform/athlete": typeof healthkit_transform_athlete;
+  "healthkit/transform/body": typeof healthkit_transform_body;
+  "healthkit/transform/daily": typeof healthkit_transform_daily;
+  "healthkit/transform/maps/activityType": typeof healthkit_transform_maps_activityType;
+  "healthkit/transform/maps/menstruationFlow": typeof healthkit_transform_maps_menstruationFlow;
+  "healthkit/transform/maps/sleepLevel": typeof healthkit_transform_maps_sleepLevel;
+  "healthkit/transform/menstruation": typeof healthkit_transform_menstruation;
+  "healthkit/transform/nutrition": typeof healthkit_transform_nutrition;
+  "healthkit/transform/sleep": typeof healthkit_transform_sleep;
+  "healthkit/transform/utils": typeof healthkit_transform_utils;
+  "healthkit/types": typeof healthkit_types;
   private: typeof private_;
   public: typeof public_;
   "strava/auth": typeof strava_auth;

package/src/component/_generated/component.ts

@@ -25,6 +25,19 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
   {
     garmin: {
       public: {
+        backfillAll: FunctionReference<
+          "action",
+          "internal",
+          {
+            clientId: string;
+            clientSecret: string;
+            endTimeInSeconds?: number;
+            startTimeInSeconds?: number;
+            userId: string;
+          },
+          any,
+          Name
+        >;
         completeGarminOAuth: FunctionReference<
           "action",
           "internal",

package/src/component/garmin/private.ts

@@ -585,7 +585,7 @@ export const processBodyCompositionsPushPayload = internalAction({
       if (!connection) {
         for (const item of userItems) {
           errors.push({
-            type: "bodyCompositions",
+            type: "body",
             id: item.summaryId ?? "unknown",
             message: `No Soma connection found for Garmin userId "${garminUserId}"`,
           });
@@ -596,7 +596,7 @@ export const processBodyCompositionsPushPayload = internalAction({
       if (!connection.active) {
         for (const item of userItems) {
           errors.push({
-            type: "bodyCompositions",
+            type: "body",
             id: item.summaryId ?? "unknown",
             message: `Garmin connection for userId "${garminUserId}" is inactive`,
           });
@@ -611,7 +611,7 @@ export const processBodyCompositionsPushPayload = internalAction({
           items.push({ connectionId: connection._id, userId: connection.userId, data });
         } catch (err) {
           errors.push({
-            type: "bodyCompositions",
+            type: "body",
             id: item.summaryId ?? "unknown",
             message: err instanceof Error ? err.message : String(err),
           });
@@ -677,7 +677,7 @@ export const processDailiesPushPayload = internalAction({
       if (!connection) {
         for (const item of userItems) {
           errors.push({
-            type: "dailies",
+            type: "daily",
             id: item.summaryId ?? "unknown",
             message: `No Soma connection found for Garmin userId "${garminUserId}"`,
           });
@@ -688,7 +688,7 @@ export const processDailiesPushPayload = internalAction({
       if (!connection.active) {
         for (const item of userItems) {
           errors.push({
-            type: "dailies",
+            type: "daily",
             id: item.summaryId ?? "unknown",
             message: `Garmin connection for userId "${garminUserId}" is inactive`,
           });
@@ -703,7 +703,7 @@ export const processDailiesPushPayload = internalAction({
           items.push({ connectionId: connection._id, userId: connection.userId, data });
         } catch (err) {
           errors.push({
-            type: "dailies",
+            type: "daily",
             id: item.summaryId ?? "unknown",
             message: err instanceof Error ? err.message : String(err),
           });
@@ -861,7 +861,7 @@ export const processHRVSummaryPushPayload = internalAction({
       if (!connection) {
         for (const item of userItems) {
           errors.push({
-            type: "hrvSummary",
+            type: "hrv",
             id: item.summaryId ?? "unknown",
             message: `No Soma connection found for Garmin userId "${garminUserId}"`,
           });
@@ -872,7 +872,7 @@ export const processHRVSummaryPushPayload = internalAction({
       if (!connection.active) {
         for (const item of userItems) {
           errors.push({
-            type: "hrvSummary",
+            type: "hrv",
             id: item.summaryId ?? "unknown",
             message: `Garmin connection for userId "${garminUserId}" is inactive`,
           });
@@ -887,7 +887,7 @@ export const processHRVSummaryPushPayload = internalAction({
           items.push({ connectionId: connection._id, userId: connection.userId, data });
         } catch (err) {
           errors.push({
-            type: "hrvSummary",
+            type: "hrv",
             id: item.summaryId ?? "unknown",
             message: err instanceof Error ? err.message : String(err),
           });
@@ -1594,7 +1594,7 @@ export const processMenstrualCycleTrackingPushPayload = internalAction({
       if (!connection) {
         for (const item of userItems) {
           errors.push({
-            type: "menstrualCycleTracking",
+            type: "menstruation",
             id: item.summaryId ?? "unknown",
             message: `No Soma connection found for Garmin userId "${garminUserId}"`,
           });
@@ -1605,7 +1605,7 @@ export const processMenstrualCycleTrackingPushPayload = internalAction({
       if (!connection.active) {
         for (const item of userItems) {
           errors.push({
-            type: "menstrualCycleTracking",
+            type: "menstruation",
             id: item.summaryId ?? "unknown",
             message: `Garmin connection for userId "${garminUserId}" is inactive`,
           });
@@ -1619,7 +1619,7 @@ export const processMenstrualCycleTrackingPushPayload = internalAction({
           items.push({ connectionId: connection._id, userId: connection.userId, data });
         } catch (err) {
           errors.push({
-            type: "menstrualCycleTracking",
+            type: "menstruation",
             id: item.summaryId ?? "unknown",
             message: err instanceof Error ? err.message : String(err),
           });

package/src/component/garmin/public.ts

@@ -18,7 +18,7 @@ import {
   createWellnessClient,
   createTrainingClient,
 } from "./client.js";
-import { buildTimeRangeQuery } from "./utils.js";
+import { buildTimeRangeQuery, buildChunkedTimeRangeQueries, buildBackfillQuery, buildChunkedBackfillQueries } from "./utils.js";
 import {
   createWorkoutV2 as sdkCreateWorkoutV2,
   createWorkoutSchedule as sdkCreateWorkoutSchedule,
@@ -42,6 +42,19 @@ import {
   getStressDetails,
   getPulseox,
   getRespiration,
+  getBackfillDailies,
+  getBackfillSleeps,
+  getBackfillBodycomps,
+  getBackfillMct,
+  getBackfillBloodPressures,
+  getBackfillSkinTemp,
+  getBackfillUserMetrics,
+  getBackfillHrv,
+  getBackfillStressDetails,
+  getBackfillPulseox,
+  getBackfillRespirationEpoch,
+  getBackfillActivities,
+  getBackfillActivityDetails,
 } from "./types/wellnessApi/sdk.gen";
 import { transformActivity } from "./transform/activity.js";
 import { transformDailies } from "./transform/dailies.js";
@@ -57,7 +70,7 @@ import { transformPulseOx } from "./transform/pulseOx.js";
 import { transformRespiration } from "./transform/respiration.js";
 import { transformPlannedWorkoutToGarmin } from "./transform/plannedWorkout.js";
 import { api, internal } from "../_generated/api";
-import type { SomaError } from "../validators/shared.js";
+import type { SomaError, SomaErrorType } from "../validators/shared.js";
 
 // ─── OAuth ──────────────────────────────────────────────────────────────────
 
@@ -187,8 +200,8 @@ export const disconnectGarmin = action({
       try {
         const wellnessClient = createWellnessClient(tokenDoc.accessToken);
         await sdkDereg({ client: wellnessClient });
-      } catch {
-        // Deregistration is best-effort; proceed with local cleanup
+      } catch (err) {
+        console.warn("[garmin:disconnect] Best-effort deregistration failed:", err instanceof Error ? err.message : err);
       }
     }
 
@@ -507,11 +520,11 @@ export const pullSkinTemperature = action({
           await ctx.runMutation(api.public.ingestBody, { connectionId, userId: args.userId, ...data });
           synced.skinTemp++;
         } catch (err) {
-          errors.push({ type: "skinTemp", id: skin.summaryId ?? skin.calendarDate ?? "unknown", message: err instanceof Error ? err.message : String(err) });
+          errors.push({ type: "skinTemperature", id: skin.summaryId ?? skin.calendarDate ?? "unknown", message: err instanceof Error ? err.message : String(err) });
         }
       }
     } catch (err) {
-      errors.push({ type: "skinTemp", id: "fetch", message: err instanceof Error ? err.message : String(err) });
+      errors.push({ type: "skinTemperature", id: "fetch", message: err instanceof Error ? err.message : String(err) });
     }
 
     await ctx.runMutation(api.public.updateConnection, { connectionId, lastDataUpdate: new Date().toISOString() });
@@ -740,14 +753,15 @@ export const pullAll = action({
       startTimeInSeconds: args.startTimeInSeconds,
       endTimeInSeconds: args.endTimeInSeconds,
     };
-    const pullFns = [
-      { ref: api.garmin.public.pullActivities, name: "activities" },
-      { ref: api.garmin.public.pullDailies, name: "dailies" },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const pullFns: Array<{ ref: any; name: SomaErrorType }> = [
+      { ref: api.garmin.public.pullActivities, name: "activity" },
+      { ref: api.garmin.public.pullDailies, name: "daily" },
       { ref: api.garmin.public.pullSleep, name: "sleep" },
       { ref: api.garmin.public.pullBody, name: "body" },
       { ref: api.garmin.public.pullMenstruation, name: "menstruation" },
-      { ref: api.garmin.public.pullBloodPressures, name: "bloodPressures" },
-      { ref: api.garmin.public.pullSkinTemperature, name: "skinTemp" },
+      { ref: api.garmin.public.pullBloodPressures, name: "bloodPressure" },
+      { ref: api.garmin.public.pullSkinTemperature, name: "skinTemperature" },
       { ref: api.garmin.public.pullUserMetrics, name: "userMetrics" },
       { ref: api.garmin.public.pullHRV, name: "hrv" },
       { ref: api.garmin.public.pullStressDetails, name: "stressDetails" },
@@ -774,6 +788,147 @@ export const pullAll = action({
 });
 
 
+// ─── Backfill ─────────────────────────────────────────────────────────────
+
+/**
+ * Request historical data from Garmin's backfill API for all summary types.
+ *
+ * Unlike pull functions (which query by upload time with a 24h max window),
+ * backfill requests data by the time it was *recorded* on the device.
+ * Garmin processes backfill asynchronously (HTTP 202) and delivers data
+ * via push/ping webhooks — no data is returned synchronously.
+ *
+ * Health endpoints accept up to 90 days per request.
+ * Activity endpoints accept up to 30 days per request (auto-chunked).
+ *
+ * Defaults to the last 90 days when no time range is provided.
+ */
+export const backfillAll = action({
+  args: {
+    userId: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    startTimeInSeconds: v.optional(v.number()),
+    endTimeInSeconds: v.optional(v.number()),
+  },
+  handler: async (ctx, args) => {
+    const { connectionId, accessToken } = await ctx.runAction(
+      internal.private.resolveConnectionAndAccessToken,
+      {
+        userId: args.userId,
+        provider: "GARMIN",
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+      },
+    );
+
+    const wellnessClient = createWellnessClient(accessToken);
+    const timeInput = {
+      startTimeInSeconds: args.startTimeInSeconds,
+      endTimeInSeconds: args.endTimeInSeconds,
+    };
+
+    // Health endpoints: up to 90 days, single request each
+    const healthQuery = buildBackfillQuery(timeInput);
+
+    // Activity endpoints: max 30 days per request, chunked
+    const activityChunks = buildChunkedBackfillQueries(timeInput);
+
+    const requested: string[] = [];
+    const errors: SomaError[] = [];
+
+    // ── Health backfills (90-day window) ──
+    const healthBackfills: Array<{
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      fn: (opts: any) => Promise<any>;
+      name: string;
+    }> = [
+      { fn: getBackfillDailies, name: "dailies" },
+      { fn: getBackfillSleeps, name: "sleeps" },
+      { fn: getBackfillBodycomps, name: "bodyComps" },
+      { fn: getBackfillMct, name: "mct" },
+      { fn: getBackfillBloodPressures, name: "bloodPressures" },
+      { fn: getBackfillSkinTemp, name: "skinTemp" },
+      { fn: getBackfillUserMetrics, name: "userMetrics" },
+      { fn: getBackfillHrv, name: "hrv" },
+      { fn: getBackfillStressDetails, name: "stressDetails" },
+      { fn: getBackfillPulseox, name: "pulseOx" },
+      { fn: getBackfillRespirationEpoch, name: "respiration" },
+    ];
+
+    for (const { fn, name } of healthBackfills) {
+      try {
+        const { error } = await fn({
+          client: wellnessClient,
+          query: healthQuery,
+        });
+        if (error) {
+          errors.push({
+            type: name as SomaErrorType,
+            id: "backfill",
+            message: JSON.stringify(error),
+          });
+        } else {
+          requested.push(name);
+        }
+      } catch (err) {
+        errors.push({
+          type: name as SomaErrorType,
+          id: "backfill",
+          message: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
+    // ── Activity backfills (30-day chunked windows) ──
+    const activityBackfills: Array<{
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      fn: (opts: any) => Promise<any>;
+      name: string;
+    }> = [
+      { fn: getBackfillActivities, name: "activities" },
+      { fn: getBackfillActivityDetails, name: "activityDetails" },
+    ];
+
+    for (const { fn, name } of activityBackfills) {
+      let chunkErrors = 0;
+      for (const chunk of activityChunks) {
+        try {
+          const { error } = await fn({
+            client: wellnessClient,
+            query: chunk,
+          });
+          if (error) {
+            chunkErrors++;
+            errors.push({
+              type: name as SomaErrorType,
+              id: "backfill",
+              message: JSON.stringify(error),
+            });
+          }
+        } catch (err) {
+          chunkErrors++;
+          errors.push({
+            type: name as SomaErrorType,
+            id: "backfill",
+            message: err instanceof Error ? err.message : String(err),
+          });
+        }
+      }
+      if (chunkErrors < activityChunks.length) {
+        requested.push(name);
+      }
+    }
+
+    await ctx.runMutation(api.public.updateConnection, {
+      connectionId,
+      lastDataUpdate: new Date().toISOString(),
+    });
+
+    return { data: { requested }, errors };
+  },
+});
+
 // ─── Push ───────────────────────────────────────────────────────────────────
 
 export const pushWorkout = action({

package/src/component/garmin/utils.ts

@@ -39,4 +39,106 @@ export function buildTimeRangeQuery(
     uploadEndTimeInSeconds: String(uploadEndTimeInSeconds),
     token: accessToken,
   };
+}
+
+/**
+ * Build an array of time-range query objects, each spanning at most
+ * `maxRangeSeconds`.
+ *
+ * Garmin's intraday endpoints (respiration, stress, pulse-ox, epochs, HRV)
+ * enforce a maximum query window of 86 400 s (24 h). This helper splits the
+ * full requested range into consecutive, non-overlapping chunks so the caller
+ * can issue one API call per chunk and merge the results.
+ */
+export function buildChunkedTimeRangeQueries(
+  input: { startTimeInSeconds?: number; endTimeInSeconds?: number },
+  accessToken: string,
+  maxRangeSeconds: number,
+  nowSeconds = Math.floor(Date.now() / 1000),
+  defaultSyncDays = 30,
+) {
+  const start =
+    input.startTimeInSeconds ?? nowSeconds - defaultSyncDays * 86400;
+  const end = input.endTimeInSeconds ?? nowSeconds;
+
+  const chunks: Array<{
+    uploadStartTimeInSeconds: string;
+    uploadEndTimeInSeconds: string;
+    token: string;
+  }> = [];
+
+  for (let chunkStart = start; chunkStart < end; chunkStart += maxRangeSeconds) {
+    const chunkEnd = Math.min(chunkStart + maxRangeSeconds, end);
+    chunks.push({
+      uploadStartTimeInSeconds: String(chunkStart),
+      uploadEndTimeInSeconds: String(chunkEnd),
+      token: accessToken,
+    });
+  }
+
+  return chunks;
+}
+
+// ─── Backfill Query Helpers ────────────────────────────────────────────────
+
+const BACKFILL_MAX_HEALTH_DAYS = 90;
+const BACKFILL_MAX_ACTIVITY_DAYS = 30;
+
+/**
+ * Build a backfill query object for Garmin's `/rest/backfill/*` endpoints.
+ *
+ * Backfill uses `summaryStartTimeInSeconds` / `summaryEndTimeInSeconds`
+ * (based on when data was *recorded*, not uploaded) and does NOT take a
+ * `token` query param — auth is via Bearer header only.
+ *
+ * Health endpoints accept up to 90 days per request.
+ * Activity endpoints accept up to 30 days per request.
+ */
+export function buildBackfillQuery(
+  input: { startTimeInSeconds?: number; endTimeInSeconds?: number },
+  nowSeconds = Math.floor(Date.now() / 1000),
+  defaultDays = BACKFILL_MAX_HEALTH_DAYS,
+) {
+  const summaryStartTimeInSeconds =
+    input.startTimeInSeconds ?? nowSeconds - defaultDays * 86400;
+  const summaryEndTimeInSeconds = input.endTimeInSeconds ?? nowSeconds;
+
+  return {
+    summaryStartTimeInSeconds: String(summaryStartTimeInSeconds),
+    summaryEndTimeInSeconds: String(summaryEndTimeInSeconds),
+  };
+}
+
+/**
+ * Build an array of backfill query objects, each spanning at most
+ * `maxDays` days.
+ *
+ * Activity backfill endpoints enforce a 30-day max per request.
+ * This splits a wider range into consecutive, non-overlapping chunks.
+ */
+export function buildChunkedBackfillQueries(
+  input: { startTimeInSeconds?: number; endTimeInSeconds?: number },
+  maxDays = BACKFILL_MAX_ACTIVITY_DAYS,
+  nowSeconds = Math.floor(Date.now() / 1000),
+  defaultDays = BACKFILL_MAX_HEALTH_DAYS,
+) {
+  const start =
+    input.startTimeInSeconds ?? nowSeconds - defaultDays * 86400;
+  const end = input.endTimeInSeconds ?? nowSeconds;
+
+  const maxRangeSeconds = maxDays * 86400;
+  const chunks: Array<{
+    summaryStartTimeInSeconds: string;
+    summaryEndTimeInSeconds: string;
+  }> = [];
+
+  for (let chunkStart = start; chunkStart < end; chunkStart += maxRangeSeconds) {
+    const chunkEnd = Math.min(chunkStart + maxRangeSeconds, end);
+    chunks.push({
+      summaryStartTimeInSeconds: String(chunkStart),
+      summaryEndTimeInSeconds: String(chunkEnd),
+    });
+  }
+
+  return chunks;
 }

package/src/component/garmin/webhooks.ts

@@ -6,7 +6,7 @@
 import { v } from "convex/values";
 import { action, type ActionCtx } from "../_generated/server";
 import { api, internal } from "../_generated/api";
-import type { SomaError } from "../validators/shared.js";
+import type { SomaError, WebhookResult } from "../validators/shared.js";
 import {
   garminSkinTemperaturePingPayloadSchema,
   garminSkinTemperaturePushPayloadSchema,
@@ -104,12 +104,6 @@ function isWebhookPushMode(payload: unknown): boolean {
   return !("callbackURL" in firstItem);
 }
 
-/** Shape returned by webhook handler actions (both internal processors and public handlers). */
-type WebhookResult = {
-  errors: SomaError[];
-  items: Array<{ connectionId: string; userId: string; data: Record<string, unknown> }>;
-};
-
 /**
  * Ingest transformed items from a private handler and update connections.
  * Shared orchestration logic for all push-mode webhook handlers.