@clipin/convex-wearables 0.1.3 → 0.2.1

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);
 
@@ -438,6 +448,145 @@ export const processPushPayload = action({
   },
 });
 
+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"],
@@ -559,9 +708,11 @@ async function upsertSummary<T extends { date: string; category: string }>(
 
   await ctx.runMutation(internal.summaries.upsert, {
     userId,
+    provider: "garmin",
     date,
     category,
     ...metrics,
+    source: "garmin",
   });
 }
 
@@ -644,6 +795,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/types.ts

@@ -113,6 +113,8 @@ export interface NormalizedDataPoint {
 export interface NormalizedDailySummary {
   date: string;
   category: string;
+  source?: string;
+  originalSourceName?: string;
   totalSteps?: number;
   totalCalories?: number;
   activeCalories?: number;

package/src/component/schema.ts

@@ -200,6 +200,10 @@ export default defineSchema({
   // -------------------------------------------------------------------------
   dailySummaries: defineTable({
     userId: v.string(),
+    provider: v.optional(providerName),
+    dataSourceId: v.optional(v.id("dataSources")),
+    source: v.optional(v.string()),
+    originalSourceName: v.optional(v.string()),
     date: v.string(), // "2026-03-15" (ISO date string)
     category: v.string(), // "activity" | "sleep" | "recovery" | "body"
 
@@ -241,6 +245,8 @@ export default defineSchema({
     bodyBattery: v.optional(v.number()),
     spo2Avg: v.optional(v.number()),
   })
+    .index("by_user_provider_category_date", ["userId", "provider", "category", "date"])
+    .index("by_user_provider_date", ["userId", "provider", "date"])
     .index("by_user_category_date", ["userId", "category", "date"])
     .index("by_user_date", ["userId", "date"]),
 
@@ -301,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

@@ -130,6 +130,20 @@ describe("sdkPush", () => {
         .collect();
     });
     expect(summaries).toHaveLength(2);
+    expect(summaries).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          provider: "google",
+          source: "health-connect",
+          category: "activity",
+        }),
+        expect.objectContaining({
+          provider: "google",
+          source: "health-connect",
+          category: "recovery",
+        }),
+      ]),
+    );
   });
 
   it("deduplicates SDK pushes by external id and source-time keys", async () => {
@@ -304,12 +318,81 @@ describe("sdkPush", () => {
 
     expect(summaries).toHaveLength(1);
     expect(summaries[0]).toMatchObject({
+      provider: "google",
+      source: "health-connect",
       category: "activity",
       totalSteps: 12345,
       totalCalories: 780,
     });
   });
 
+  it("keeps Apple and Google daily summaries separate for the same user date and category", async () => {
+    const t = convexTest(schema, modules);
+
+    await t.action(api.sdkPush.ingestNormalizedPayload, {
+      userId: "user-mixed",
+      provider: "apple",
+      sourceMetadata: {
+        source: "healthkit",
+        originalSourceName: "Apple Watch",
+      },
+      summaries: [
+        {
+          date: "2026-03-18",
+          category: "activity",
+          totalSteps: 9000,
+          activeCalories: 450,
+        },
+      ],
+    });
+
+    await t.action(api.sdkPush.ingestNormalizedPayload, {
+      userId: "user-mixed",
+      provider: "google",
+      sourceMetadata: {
+        source: "health-connect",
+        originalSourceName: "com.google.android.apps.fitness",
+      },
+      summaries: [
+        {
+          date: "2026-03-18",
+          category: "activity",
+          totalSteps: 7200,
+          activeCalories: 330,
+        },
+      ],
+    });
+
+    const summaries = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("dailySummaries")
+        .withIndex("by_user_category_date", (idx) =>
+          idx.eq("userId", "user-mixed").eq("category", "activity").eq("date", "2026-03-18"),
+        )
+        .collect();
+    });
+
+    expect(summaries).toHaveLength(2);
+    expect(summaries).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          provider: "apple",
+          source: "healthkit",
+          originalSourceName: "Apple Watch",
+          totalSteps: 9000,
+          activeCalories: 450,
+        }),
+        expect.objectContaining({
+          provider: "google",
+          source: "health-connect",
+          originalSourceName: "com.google.android.apps.fitness",
+          totalSteps: 7200,
+          activeCalories: 330,
+        }),
+      ]),
+    );
+  });
+
   it("batches large data-point payloads across multiple writes", async () => {
     const t = convexTest(schema, modules);
 

package/src/component/sdkPush.ts

@@ -93,6 +93,8 @@ const sdkDataPointValidator = v.object({
 const sdkSummaryValidator = v.object({
   date: v.string(),
   category: v.string(),
+  source: v.optional(v.string()),
+  originalSourceName: v.optional(v.string()),
   totalSteps: v.optional(v.number()),
   totalCalories: v.optional(v.number()),
   activeCalories: v.optional(v.number()),
@@ -360,7 +362,10 @@ export const ingestNormalizedPayload = action({
     for (const summary of summaries) {
       await ctx.runMutation(internal.summaries.upsert, {
         userId: args.userId,
+        provider: args.provider,
         ...summary,
+        source: summary.source ?? defaultMetadata.source,
+        originalSourceName: summary.originalSourceName ?? defaultMetadata.originalSourceName,
       });
     }
 

package/src/component/summaries.test.ts

@@ -1,5 +1,6 @@
 import { convexTest } from "convex-test";
 import { describe, expect, it } from "vitest";
+import { api, internal } from "./_generated/api";
 import schema from "./schema";
 import { modules } from "./test.setup";
 
@@ -81,6 +82,62 @@ describe("summaries", () => {
       expect(summaries[0].totalSteps).toBe(10000);
       expect(summaries[0].activeMinutes).toBe(45);
     });
+
+    it("upserts summaries by user provider category and date", async () => {
+      const t = convexTest(schema, modules);
+
+      await t.mutation(internal.summaries.upsert, {
+        userId: "user-1",
+        provider: "garmin",
+        date: "2026-03-15",
+        category: "activity",
+        totalSteps: 10000,
+        activeCalories: 600,
+      });
+
+      await t.mutation(internal.summaries.upsert, {
+        userId: "user-1",
+        provider: "apple",
+        date: "2026-03-15",
+        category: "activity",
+        source: "healthkit",
+        originalSourceName: "Apple Watch",
+        totalSteps: 8500,
+        activeCalories: 430,
+      });
+
+      await t.mutation(internal.summaries.upsert, {
+        userId: "user-1",
+        provider: "garmin",
+        date: "2026-03-15",
+        category: "activity",
+        totalSteps: 11000,
+      });
+
+      const summaries = await t.run(async (ctx) => {
+        return await ctx.db
+          .query("dailySummaries")
+          .withIndex("by_user_category_date", (idx) =>
+            idx.eq("userId", "user-1").eq("category", "activity").eq("date", "2026-03-15"),
+          )
+          .collect();
+      });
+
+      expect(summaries).toHaveLength(2);
+      const garmin = summaries.find((summary) => summary.provider === "garmin");
+      const apple = summaries.find((summary) => summary.provider === "apple");
+
+      expect(garmin).toMatchObject({
+        totalSteps: 11000,
+        activeCalories: 600,
+      });
+      expect(apple).toMatchObject({
+        source: "healthkit",
+        originalSourceName: "Apple Watch",
+        totalSteps: 8500,
+        activeCalories: 430,
+      });
+    });
   });
 
   describe("getDailySummaries", () => {
@@ -156,6 +213,48 @@ describe("summaries", () => {
       expect(sleep).toHaveLength(1);
       expect(sleep[0].sleepDurationMinutes).toBe(480);
     });
+
+    it("filters summaries by provider when requested", async () => {
+      const t = convexTest(schema, modules);
+
+      await t.mutation(internal.summaries.upsert, {
+        userId: "user-1",
+        provider: "garmin",
+        date: "2026-03-15",
+        category: "activity",
+        totalSteps: 10000,
+      });
+      await t.mutation(internal.summaries.upsert, {
+        userId: "user-1",
+        provider: "google",
+        date: "2026-03-15",
+        category: "activity",
+        source: "health-connect",
+        totalSteps: 9200,
+      });
+
+      const google = await t.query(api.summaries.getDailySummaries, {
+        userId: "user-1",
+        provider: "google",
+        category: "activity",
+        startDate: "2026-03-15",
+        endDate: "2026-03-15",
+      });
+      const mixed = await t.query(api.summaries.getDailySummaries, {
+        userId: "user-1",
+        category: "activity",
+        startDate: "2026-03-15",
+        endDate: "2026-03-15",
+      });
+
+      expect(google).toHaveLength(1);
+      expect(google[0]).toMatchObject({
+        provider: "google",
+        source: "health-connect",
+        totalSteps: 9200,
+      });
+      expect(mixed).toHaveLength(2);
+    });
   });
 
   describe("getByUserDate", () => {