@clipin/convex-wearables 0.2.0 → 0.3.0

package/src/component/garminWebhooks.ts

@@ -8,7 +8,13 @@
 import { v } from "convex/values";
 import { api, internal } from "./_generated/api";
 import type { Doc, Id } from "./_generated/dataModel";
-import { type ActionCtx, action } from "./_generated/server";
+import {
+  type ActionCtx,
+  action,
+  internalAction,
+  internalMutation,
+  internalQuery,
+} from "./_generated/server";
 import {
   type GarminPushPayload,
   normalizeActivity,
@@ -34,6 +40,8 @@ import {
 } from "./providers/garmin";
 
 const DATA_POINT_BATCH_SIZE = 500;
+const PENDING_GARMIN_PUSH_TTL_MS = 30 * 60 * 1000;
+const PENDING_GARMIN_PUSH_REPLAY_LIMIT = 20;
 
 function decodePushPayload(args: { payload?: unknown; payloadJson?: string }): GarminPushPayload {
   if (args.payloadJson !== undefined) {
@@ -61,6 +69,8 @@ export const processPushPayload = action({
     const payload = decodePushPayload(args);
     const signalBuckets = new Map<string, Set<string>>();
 
+    await queuePendingPayloadForInactiveConnections(ctx, payload, args.garminClientId);
+
     await processActivityEntries(ctx, payload.activities, "activities", signalBuckets);
     await processActivityEntries(ctx, payload.activityDetails, "activityDetails", signalBuckets);
 
@@ -234,8 +244,12 @@ export const processPushPayload = action({
       }
     }
 
-    if (payload.respiration?.length) {
-      for (const respiration of payload.respiration) {
+    const respirationEntries =
+      payload.allDayRespiration && payload.allDayRespiration.length > 0
+        ? payload.allDayRespiration
+        : payload.respiration;
+    if (respirationEntries?.length) {
+      for (const respiration of respirationEntries) {
         const connection = await resolveConnection(ctx, respiration.userId);
         if (!connection) continue;
 
@@ -247,12 +261,14 @@ export const processPushPayload = action({
           dataSourceId,
           normalizeRespirationDataPoints(respiration),
         );
-        addSignal(signalBuckets, "respiration", connection._id);
+        addSignal(signalBuckets, "allDayRespiration", connection._id);
       }
     }
 
-    if (payload.pulseOx?.length) {
-      for (const pulseOx of payload.pulseOx) {
+    const pulseOxEntries =
+      payload.pulseOx && payload.pulseOx.length > 0 ? payload.pulseOx : payload.pulseox;
+    if (pulseOxEntries?.length) {
+      for (const pulseOx of pulseOxEntries) {
         const connection = await resolveConnection(ctx, pulseOx.userId);
         if (!connection) continue;
 
@@ -334,8 +350,12 @@ export const processPushPayload = action({
       }
     }
 
-    if (payload.moveiq?.length) {
-      for (const moveIQ of payload.moveiq) {
+    const moveIQEntries =
+      payload.moveIQActivities && payload.moveIQActivities.length > 0
+        ? payload.moveIQActivities
+        : payload.moveiq;
+    if (moveIQEntries?.length) {
+      for (const moveIQ of moveIQEntries) {
         const connection = await resolveConnection(ctx, moveIQ.userId);
         if (!connection) continue;
 
@@ -355,7 +375,7 @@ export const processPushPayload = action({
           externalId: event.externalId,
         });
 
-        addSignal(signalBuckets, "moveiq", connection._id);
+        addSignal(signalBuckets, "moveIQActivities", connection._id);
       }
     }
 
@@ -434,10 +454,158 @@ export const processPushPayload = action({
       }
     }
 
+    const syncedConnectionIds = new Set(
+      [...signalBuckets.values()].flatMap((connectionIds) => [...connectionIds]),
+    );
+    for (const connectionId of syncedConnectionIds) {
+      await ctx.runMutation(internal.connections.markSynced, {
+        connectionId: connectionId as Id<"connections">,
+      });
+    }
+
     return null;
   },
 });
 
+export const replayPendingForConnection = internalAction({
+  args: {
+    connectionId: v.id("connections"),
+  },
+  returns: v.object({
+    failed: v.number(),
+    replayed: v.number(),
+    skipped: v.number(),
+  }),
+  handler: async (ctx, args) => {
+    const skipped = await ctx.runMutation(internal.garminWebhooks.markExpiredPendingForConnection, {
+      connectionId: args.connectionId,
+      now: Date.now(),
+    });
+    const pendingPayloads = await ctx.runQuery(internal.garminWebhooks.getReplayablePending, {
+      connectionId: args.connectionId,
+      now: Date.now(),
+    });
+    let failed = 0;
+    let replayed = 0;
+
+    for (const pending of pendingPayloads) {
+      try {
+        await ctx.runAction(api.garminWebhooks.processPushPayload, {
+          garminClientId: pending.garminClientId,
+          payloadJson: pending.payloadJson,
+        });
+        await ctx.runMutation(internal.garminWebhooks.markPendingReplayed, {
+          pendingId: pending._id,
+        });
+        replayed += 1;
+      } catch (error) {
+        failed += 1;
+        await ctx.runMutation(internal.garminWebhooks.markPendingFailed, {
+          pendingId: pending._id,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+    }
+
+    return { failed, replayed, skipped };
+  },
+});
+
+export const getReplayablePending = internalQuery({
+  args: {
+    connectionId: v.id("connections"),
+    now: v.number(),
+  },
+  returns: v.array(v.any()),
+  handler: async (ctx, args) => {
+    const rows = await ctx.db
+      .query("pendingGarminPushPayloads")
+      .withIndex("by_connection_status", (idx) =>
+        idx.eq("connectionId", args.connectionId).eq("status", "pending"),
+      )
+      .order("asc")
+      .take(PENDING_GARMIN_PUSH_REPLAY_LIMIT);
+
+    return rows.filter((row) => row.expiresAt > args.now);
+  },
+});
+
+export const storePendingPayload = internalMutation({
+  args: {
+    connectionId: v.id("connections"),
+    userId: v.string(),
+    providerUserId: v.string(),
+    garminClientId: v.string(),
+    payloadJson: v.string(),
+    receivedAt: v.number(),
+    expiresAt: v.number(),
+  },
+  returns: v.id("pendingGarminPushPayloads"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("pendingGarminPushPayloads", {
+      ...args,
+      status: "pending",
+    });
+  },
+});
+
+export const markPendingReplayed = internalMutation({
+  args: {
+    pendingId: v.id("pendingGarminPushPayloads"),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.pendingId, {
+      replayedAt: Date.now(),
+      status: "replayed",
+      error: undefined,
+    });
+    return null;
+  },
+});
+
+export const markPendingFailed = internalMutation({
+  args: {
+    pendingId: v.id("pendingGarminPushPayloads"),
+    error: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.patch(args.pendingId, {
+      error: args.error,
+      status: "failed",
+    });
+    return null;
+  },
+});
+
+export const markExpiredPendingForConnection = internalMutation({
+  args: {
+    connectionId: v.id("connections"),
+    now: v.number(),
+  },
+  returns: v.number(),
+  handler: async (ctx, args) => {
+    const expired = await ctx.db
+      .query("pendingGarminPushPayloads")
+      .withIndex("by_connection_status", (idx) =>
+        idx.eq("connectionId", args.connectionId).eq("status", "pending"),
+      )
+      .filter((q) => q.lte(q.field("expiresAt"), args.now))
+      .collect();
+
+    await Promise.all(
+      expired.map((row) =>
+        ctx.db.patch(row._id, {
+          status: "expired",
+        }),
+      ),
+    );
+
+    return expired.length;
+  },
+});
+
 async function processActivityEntries(
   ctx: Pick<ActionCtx, "runQuery" | "runMutation">,
   activities: GarminPushPayload["activities"] | GarminPushPayload["activityDetails"],
@@ -595,10 +763,10 @@ function getPayloadItemCount(payload: GarminPushPayload, dataType: string): numb
       return payload.hrv?.length;
     case "stressDetails":
       return payload.stressDetails?.length;
-    case "respiration":
-      return payload.respiration?.length;
+    case "allDayRespiration":
+      return payload.allDayRespiration?.length ?? payload.respiration?.length;
     case "pulseOx":
-      return payload.pulseOx?.length;
+      return payload.pulseOx?.length ?? payload.pulseox?.length;
     case "bloodPressures":
       return payload.bloodPressures?.length;
     case "userMetrics":
@@ -607,8 +775,8 @@ function getPayloadItemCount(payload: GarminPushPayload, dataType: string): numb
       return payload.skinTemp?.length;
     case "healthSnapshot":
       return payload.healthSnapshot?.length;
-    case "moveiq":
-      return payload.moveiq?.length;
+    case "moveIQActivities":
+      return payload.moveIQActivities?.length ?? payload.moveiq?.length;
     case "mct":
       return payload.menstrualCycleTracking && payload.menstrualCycleTracking.length > 0
         ? payload.menstrualCycleTracking.length
@@ -646,6 +814,103 @@ async function resolveConnection(
   return connection;
 }
 
+function collectGarminUserIds(payload: GarminPushPayload): string[] {
+  const userIds = new Set<string>();
+  const maybeAdd = (entry: { userId?: unknown } | null | undefined) => {
+    if (typeof entry?.userId === "string" && entry.userId.length > 0) {
+      userIds.add(entry.userId);
+    }
+  };
+
+  for (const entry of payload.activities ?? []) maybeAdd(entry);
+  for (const entry of payload.activityDetails ?? []) maybeAdd(entry);
+  for (const entry of payload.sleeps ?? []) maybeAdd(entry);
+  for (const entry of payload.dailies ?? []) maybeAdd(entry);
+  for (const entry of payload.epochs ?? []) maybeAdd(entry);
+  for (const entry of payload.bodyComps ?? []) maybeAdd(entry);
+  for (const entry of payload.hrv ?? []) maybeAdd(entry);
+  for (const entry of payload.stressDetails ?? []) maybeAdd(entry);
+  for (const entry of payload.respiration ?? []) maybeAdd(entry);
+  for (const entry of payload.pulseOx ?? []) maybeAdd(entry);
+  for (const entry of payload.bloodPressures ?? []) maybeAdd(entry);
+  for (const entry of payload.userMetrics ?? []) maybeAdd(entry);
+  for (const entry of payload.skinTemp ?? []) maybeAdd(entry);
+  for (const entry of payload.healthSnapshot ?? []) maybeAdd(entry);
+  for (const entry of payload.moveiq ?? []) maybeAdd(entry);
+  for (const entry of payload.menstrualCycleTracking ?? []) maybeAdd(entry);
+  for (const entry of payload.mct ?? []) maybeAdd(entry);
+  for (const entry of payload.userPermissionsChange ?? []) maybeAdd(entry);
+  for (const entry of payload.deregistrations ?? []) maybeAdd(entry);
+
+  return [...userIds];
+}
+
+function filterGarminPayloadByUserId(
+  payload: GarminPushPayload,
+  providerUserId: string,
+): GarminPushPayload {
+  const filterEntries = <T extends { userId?: unknown }>(entries: T[] | undefined): T[] =>
+    (entries ?? []).filter((entry) => entry.userId === providerUserId);
+
+  return {
+    activities: filterEntries(payload.activities),
+    activityDetails: filterEntries(payload.activityDetails),
+    sleeps: filterEntries(payload.sleeps),
+    dailies: filterEntries(payload.dailies),
+    epochs: filterEntries(payload.epochs),
+    bodyComps: filterEntries(payload.bodyComps),
+    hrv: filterEntries(payload.hrv),
+    stressDetails: filterEntries(payload.stressDetails),
+    respiration: filterEntries(payload.respiration),
+    pulseOx: filterEntries(payload.pulseOx),
+    bloodPressures: filterEntries(payload.bloodPressures),
+    userMetrics: filterEntries(payload.userMetrics),
+    skinTemp: filterEntries(payload.skinTemp),
+    healthSnapshot: filterEntries(payload.healthSnapshot),
+    moveiq: filterEntries(payload.moveiq),
+    menstrualCycleTracking: filterEntries(payload.menstrualCycleTracking),
+    mct: filterEntries(payload.mct),
+    userPermissionsChange: filterEntries(payload.userPermissionsChange),
+    deregistrations: filterEntries(payload.deregistrations),
+  };
+}
+
+async function queuePendingPayloadForInactiveConnections(
+  ctx: Pick<ActionCtx, "runMutation" | "runQuery">,
+  payload: GarminPushPayload,
+  garminClientId: string,
+) {
+  const userIds = collectGarminUserIds(payload);
+  if (userIds.length === 0) {
+    return;
+  }
+
+  const receivedAt = Date.now();
+
+  for (const providerUserId of userIds) {
+    const conn = (await ctx.runQuery(internal.connections.getByProviderUser, {
+      provider: "garmin",
+      providerUserId,
+    })) as Doc<"connections"> | null;
+
+    if (!conn || conn.status === "active") {
+      continue;
+    }
+
+    const payloadJson = JSON.stringify(filterGarminPayloadByUserId(payload, providerUserId));
+
+    await ctx.runMutation(internal.garminWebhooks.storePendingPayload, {
+      connectionId: conn._id,
+      userId: conn.userId,
+      providerUserId,
+      garminClientId,
+      payloadJson,
+      receivedAt,
+      expiresAt: receivedAt + PENDING_GARMIN_PUSH_TTL_MS,
+    });
+  }
+}
+
 /**
  * Resolve a Garmin userId to a dataSource ID, creating one if needed.
  */

package/src/component/oauthActions.ts

@@ -192,6 +192,12 @@ export const handleCallback = action({
       source: oauthState.provider,
     });
 
+    if (oauthState.provider === "garmin") {
+      await ctx.runAction(internal.garminWebhooks.replayPendingForConnection, {
+        connectionId,
+      });
+    }
+
     return {
       provider: oauthState.provider,
       userId: oauthState.userId,

package/src/component/providers/garmin.ts

@@ -148,6 +148,7 @@ export interface GarminHrv {
   userId: string;
   summaryId?: string;
   startTimeInSeconds: number;
+  startTimeOffsetInSeconds?: number;
   calendarDate?: string;
   lastNightAvg?: number;
   hrvValues?: Record<string, number>;
@@ -258,12 +259,15 @@ export interface GarminPushPayload {
   bodyComps?: GarminBodyComp[];
   hrv?: GarminHrv[];
   stressDetails?: GarminStressDetails[];
+  allDayRespiration?: GarminRespiration[];
   respiration?: GarminRespiration[];
   pulseOx?: GarminPulseOx[];
+  pulseox?: GarminPulseOx[];
   bloodPressures?: GarminBloodPressure[];
   userMetrics?: GarminUserMetrics[];
   skinTemp?: GarminSkinTemp[];
   healthSnapshot?: GarminHealthSnapshot[];
+  moveIQActivities?: GarminMoveIQ[];
   moveiq?: GarminMoveIQ[];
   menstrualCycleTracking?: GarminMCTSummary[];
   mct?: GarminMCTSummary[];
@@ -282,6 +286,13 @@ function isoDateFromCalendarDate(
   return calendarDate ?? isoDateFromTimestamp(fallbackTimestampMs);
 }
 
+function isoDateFromTimestampWithOffset(timestampMs: number, offsetSeconds?: number): string {
+  if (offsetSeconds === undefined) {
+    return isoDateFromTimestamp(timestampMs);
+  }
+  return isoDateFromTimestamp(timestampMs + offsetSeconds * 1000);
+}
+
 function calendarDateToMiddayTimestamp(calendarDate: string | undefined): number | null {
   if (!calendarDate) {
     return null;
@@ -541,8 +552,9 @@ export function normalizeSleep(sleep: GarminSleep): NormalizedEvent {
 }
 
 export function normalizeSleepSummary(sleep: GarminSleep): NormalizedDailySummary {
+  const endMs = (sleep.startTimeInSeconds + sleep.durationInSeconds) * 1000;
   return {
-    date: isoDateFromTimestamp(sleep.startTimeInSeconds * 1000),
+    date: isoDateFromTimestampWithOffset(endMs, sleep.startTimeOffsetInSeconds),
     category: "sleep",
     sleepDurationMinutes: Math.floor(sleep.durationInSeconds / 60),
     sleepEfficiency: sleep.overallSleepScore?.value,
@@ -734,7 +746,7 @@ export function normalizeHrvDataPoints(hrv: GarminHrv): NormalizedDataPoint[] {
   const points: NormalizedDataPoint[] = [];
   if (hrv.lastNightAvg != null) {
     points.push({
-      seriesType: "heart_rate_variability_sdnn",
+      seriesType: "heart_rate_variability_rmssd",
       recordedAt: hrv.startTimeInSeconds * 1000,
       value: hrv.lastNightAvg,
       externalId: hrv.summaryId,
@@ -745,7 +757,7 @@ export function normalizeHrvDataPoints(hrv: GarminHrv): NormalizedDataPoint[] {
     ...buildOffsetDataPoints(
       hrv.hrvValues,
       hrv.startTimeInSeconds,
-      "heart_rate_variability_sdnn",
+      "heart_rate_variability_rmssd",
       hrv.summaryId,
     ),
   );
@@ -761,7 +773,7 @@ export function normalizeHrvSummary(hrv: GarminHrv): NormalizedDailySummary | nu
   return {
     date: isoDateFromCalendarDate(hrv.calendarDate, hrv.startTimeInSeconds * 1000),
     category: "recovery",
-    hrvAvg: hrv.lastNightAvg,
+    hrvRmssd: hrv.lastNightAvg,
   };
 }
 
@@ -1138,6 +1150,7 @@ export async function triggerBackfill(
   startTimeSeconds: number,
   endTimeSeconds: number,
 ): Promise<void> {
+  const endpointDataType = normalizeBackfillDataType(dataType);
   const validTypes = [
     "activities",
     "activityDetails",
@@ -1147,23 +1160,34 @@ export async function triggerBackfill(
     "bodyComps",
     "hrv",
     "stressDetails",
-    "respiration",
+    "allDayRespiration",
     "pulseOx",
     "bloodPressures",
     "userMetrics",
     "skinTemp",
     "healthSnapshot",
-    "moveiq",
+    "moveIQActivities",
     "mct",
   ];
-  if (!validTypes.includes(dataType)) {
+  if (!validTypes.includes(endpointDataType)) {
     throw new Error(`Invalid backfill data type: ${dataType}`);
   }
 
-  await makeAuthenticatedRequest(API_BASE, `/wellness-api/rest/backfill/${dataType}`, accessToken, {
-    params: {
-      summaryStartTimeInSeconds: String(startTimeSeconds),
-      summaryEndTimeInSeconds: String(endTimeSeconds),
+  await makeAuthenticatedRequest(
+    API_BASE,
+    `/wellness-api/rest/backfill/${endpointDataType}`,
+    accessToken,
+    {
+      params: {
+        summaryStartTimeInSeconds: String(startTimeSeconds),
+        summaryEndTimeInSeconds: String(endTimeSeconds),
+      },
     },
-  });
+  );
+}
+
+function normalizeBackfillDataType(dataType: string): string {
+  if (dataType === "respiration") return "allDayRespiration";
+  if (dataType === "moveiq") return "moveIQActivities";
+  return dataType;
 }

package/src/component/schema.ts

@@ -307,6 +307,31 @@ export default defineSchema({
     updatedAt: v.optional(v.number()),
   }).index("by_provider", ["provider"]),
 
+  // -------------------------------------------------------------------------
+  // Pending Garmin Push Payloads — short-lived replay queue for OAuth reconnect
+  // races where Garmin pushes data before the connection is active again.
+  // -------------------------------------------------------------------------
+  pendingGarminPushPayloads: defineTable({
+    connectionId: v.id("connections"),
+    userId: v.string(),
+    providerUserId: v.string(),
+    garminClientId: v.string(),
+    payloadJson: v.string(),
+    receivedAt: v.number(),
+    expiresAt: v.number(),
+    replayedAt: v.optional(v.number()),
+    status: v.union(
+      v.literal("pending"),
+      v.literal("replayed"),
+      v.literal("expired"),
+      v.literal("failed"),
+    ),
+    error: v.optional(v.string()),
+  })
+    .index("by_connection_status", ["connectionId", "status"])
+    .index("by_provider_user_status", ["providerUserId", "status"])
+    .index("by_expires", ["expiresAt"]),
+
   // -------------------------------------------------------------------------
   // Time-Series Policy Rules — default and preset-based storage rules
   // -------------------------------------------------------------------------

package/src/component/sdkPush.test.ts

@@ -245,7 +245,17 @@ describe("sdkPush", () => {
         model: "Pixel 9 Pro",
         softwareVersion: "Android 16",
         source: "health-connect",
+        appId: "com.thirdparty.writer",
       },
+      events: [
+        {
+          category: "workout",
+          type: "CYCLING_STATIONARY",
+          startDatetime: Date.parse("2026-03-18T08:00:00Z"),
+          endDatetime: Date.parse("2026-03-18T08:45:00Z"),
+          externalId: "hc-cycling-1",
+        },
+      ],
       dataPoints: [
         {
           seriesType: "hrv_rmssd",
@@ -271,6 +281,30 @@ describe("sdkPush", () => {
           value: 340,
           externalId: "hc-active-calories-1",
         },
+        {
+          seriesType: "POWER",
+          recordedAt: Date.parse("2026-03-18T12:03:00Z"),
+          value: 220,
+          externalId: "hc-power-1",
+        },
+        {
+          seriesType: "SPEED",
+          recordedAt: Date.parse("2026-03-18T12:04:00Z"),
+          value: 7.5,
+          externalId: "hc-speed-1",
+        },
+        {
+          seriesType: "CYCLING_PEDALING_CADENCE",
+          recordedAt: Date.parse("2026-03-18T12:05:00Z"),
+          value: 88,
+          externalId: "hc-cadence-1",
+        },
+        {
+          seriesType: "TOTAL_CALORIES_BURNED",
+          recordedAt: Date.parse("2026-03-18T12:06:00Z"),
+          value: 830,
+          externalId: "hc-total-calories-1",
+        },
       ],
       dailySummaries: [
         {
@@ -293,6 +327,22 @@ describe("sdkPush", () => {
       deviceModel: "Pixel 9 Pro",
       softwareVersion: "Android 16",
       source: "health-connect",
+      originalSourceName: "com.thirdparty.writer",
+    });
+
+    const events = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("events")
+        .withIndex("by_user_category_time", (idx) =>
+          idx.eq("userId", "user-3").eq("category", "workout"),
+        )
+        .collect();
+    });
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      type: "indoor_cycling",
+      externalId: "hc-cycling-1",
     });
 
     const points = await t.run(async (ctx) => {
@@ -304,9 +354,13 @@ describe("sdkPush", () => {
 
     expect(points.map((point) => point.seriesType).sort()).toEqual([
       "active_calories",
+      "cadence",
       "distance",
       "floors_climbed",
       "heart_rate_variability_rmssd",
+      "power",
+      "speed",
+      "total_calories",
     ]);
 
     const summaries = await t.run(async (ctx) => {