@clipin/convex-wearables 0.0.2 → 0.0.3

package/src/component/summaries.ts

@@ -0,0 +1,143 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery, query } from "./_generated/server";
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Get daily summaries for a user by category and date range.
+ * Returns one document per day — very efficient (365 docs for a full year).
+ */
+export const getDailySummaries = query({
+  args: {
+    userId: v.string(),
+    category: v.string(),
+    startDate: v.string(), // "2026-03-01"
+    endDate: v.string(), // "2026-03-15"
+  },
+  returns: v.array(v.any()),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("dailySummaries")
+      .withIndex("by_user_category_date", (idx) =>
+        idx
+          .eq("userId", args.userId)
+          .eq("category", args.category)
+          .gte("date", args.startDate)
+          .lte("date", args.endDate),
+      )
+      .collect();
+  },
+});
+
+/**
+ * Get all summaries for a user on a specific date (across all categories).
+ */
+export const getByUserDate = internalQuery({
+  args: {
+    userId: v.string(),
+    date: v.string(),
+  },
+  returns: v.array(v.any()),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("dailySummaries")
+      .withIndex("by_user_date", (idx) => idx.eq("userId", args.userId).eq("date", args.date))
+      .collect();
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Mutations
+// ---------------------------------------------------------------------------
+
+/**
+ * Upsert a daily summary. Called during data ingestion to update
+ * precomputed aggregates for the affected date.
+ */
+export const upsert = internalMutation({
+  args: {
+    userId: v.string(),
+    date: v.string(),
+    category: v.string(),
+    // All metric fields are optional — only provided fields are updated
+    totalSteps: v.optional(v.number()),
+    totalCalories: v.optional(v.number()),
+    activeCalories: v.optional(v.number()),
+    activeMinutes: v.optional(v.number()),
+    totalDistance: v.optional(v.number()),
+    floorsClimbed: v.optional(v.number()),
+    avgHeartRate: v.optional(v.number()),
+    maxHeartRate: v.optional(v.number()),
+    minHeartRate: v.optional(v.number()),
+    sleepDurationMinutes: v.optional(v.number()),
+    sleepEfficiency: v.optional(v.number()),
+    deepSleepMinutes: v.optional(v.number()),
+    remSleepMinutes: v.optional(v.number()),
+    lightSleepMinutes: v.optional(v.number()),
+    awakeDuringMinutes: v.optional(v.number()),
+    timeInBedMinutes: v.optional(v.number()),
+    hrvAvg: v.optional(v.number()),
+    hrvRmssd: v.optional(v.number()),
+    restingHeartRate: v.optional(v.number()),
+    recoveryScore: v.optional(v.number()),
+    weight: v.optional(v.number()),
+    bodyFatPercentage: v.optional(v.number()),
+    bodyMassIndex: v.optional(v.number()),
+    leanBodyMass: v.optional(v.number()),
+    bodyTemperature: v.optional(v.number()),
+    avgStressLevel: v.optional(v.number()),
+    bodyBattery: v.optional(v.number()),
+    spo2Avg: v.optional(v.number()),
+  },
+  returns: v.id("dailySummaries"),
+  handler: async (ctx, args) => {
+    const { userId, date, category, ...metrics } = args;
+
+    // Find existing summary for this user/date/category
+    const existing = await ctx.db
+      .query("dailySummaries")
+      .withIndex("by_user_category_date", (idx) =>
+        idx.eq("userId", userId).eq("category", category).eq("date", date),
+      )
+      .first();
+
+    // Filter out undefined values from metrics
+    const definedMetrics: Record<string, number> = {};
+    for (const [key, value] of Object.entries(metrics)) {
+      if (value !== undefined) {
+        definedMetrics[key] = value;
+      }
+    }
+
+    if (existing) {
+      await ctx.db.patch(existing._id, definedMetrics);
+      return existing._id;
+    }
+
+    return await ctx.db.insert("dailySummaries", {
+      userId,
+      date,
+      category,
+      ...definedMetrics,
+    });
+  },
+});
+
+/**
+ * Delete all summaries for a user. Used during account deletion.
+ */
+export const deleteByUser = internalMutation({
+  args: { userId: v.string() },
+  handler: async (ctx, args) => {
+    const summaries = await ctx.db
+      .query("dailySummaries")
+      .withIndex("by_user_date", (idx) => idx.eq("userId", args.userId))
+      .collect();
+
+    for (const summary of summaries) {
+      await ctx.db.delete(summary._id);
+    }
+  },
+});

package/src/component/syncJobs.test.ts

@@ -0,0 +1,254 @@
+import { convexTest } from "convex-test";
+import { describe, expect, it } from "vitest";
+import schema from "./schema";
+import { modules } from "./test.setup";
+
+async function seedConnection(
+  t: ReturnType<typeof convexTest>,
+  args: { userId?: string; provider?: "garmin" | "strava" } = {},
+) {
+  return await t.run(async (ctx) => {
+    return await ctx.db.insert("connections", {
+      userId: args.userId ?? "user-1",
+      provider: args.provider ?? "strava",
+      accessToken: "token",
+      status: "active",
+    });
+  });
+}
+
+describe("syncJobs", () => {
+  it("creates a sync job with pending status", async () => {
+    const t = convexTest(schema, modules);
+    const connectionId = await seedConnection(t);
+
+    const id = await t.run(async (ctx) => {
+      return await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "strava",
+        idempotencyKey: "job-1",
+        status: "queued",
+        startedAt: Date.now(),
+      });
+    });
+
+    const job = await t.run(async (ctx) => {
+      return await ctx.db.get(id);
+    });
+
+    expect(job?.status).toBe("queued");
+    expect(job?.userId).toBe("user-1");
+    expect(job?.provider).toBe("strava");
+  });
+
+  it("transitions status from queued to running to completed", async () => {
+    const t = convexTest(schema, modules);
+    const connectionId = await seedConnection(t);
+
+    const id = await t.run(async (ctx) => {
+      return await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "strava",
+        idempotencyKey: "job-2",
+        status: "queued",
+        startedAt: Date.now(),
+      });
+    });
+
+    // Move to running
+    await t.run(async (ctx) => {
+      await ctx.db.patch(id, { status: "running" });
+    });
+
+    const running = await t.run(async (ctx) => {
+      return await ctx.db.get(id);
+    });
+    expect(running?.status).toBe("running");
+
+    // Complete
+    await t.run(async (ctx) => {
+      await ctx.db.patch(id, {
+        status: "completed",
+        completedAt: Date.now(),
+        recordsProcessed: 42,
+      });
+    });
+
+    const completed = await t.run(async (ctx) => {
+      return await ctx.db.get(id);
+    });
+    expect(completed?.status).toBe("completed");
+    expect(completed?.recordsProcessed).toBe(42);
+    expect(completed?.completedAt).toBeDefined();
+  });
+
+  it("records error on failed sync job", async () => {
+    const t = convexTest(schema, modules);
+    const connectionId = await seedConnection(t, { provider: "garmin" });
+
+    const id = await t.run(async (ctx) => {
+      return await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "garmin",
+        idempotencyKey: "job-3",
+        status: "running",
+        startedAt: Date.now(),
+      });
+    });
+
+    await t.run(async (ctx) => {
+      await ctx.db.patch(id, {
+        status: "failed",
+        completedAt: Date.now(),
+        error: "Token refresh failed (401): invalid_grant",
+      });
+    });
+
+    const failed = await t.run(async (ctx) => {
+      return await ctx.db.get(id);
+    });
+
+    expect(failed?.status).toBe("failed");
+    expect(failed?.error).toContain("invalid_grant");
+  });
+
+  it("queries sync jobs by user (most recent first)", async () => {
+    const t = convexTest(schema, modules);
+    const connectionId = await seedConnection(t);
+    const otherConnectionId = await seedConnection(t, {
+      userId: "user-2",
+      provider: "garmin",
+    });
+
+    await t.run(async (ctx) => {
+      await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "strava",
+        idempotencyKey: "job-4",
+        status: "completed",
+        startedAt: 1710000000000,
+        completedAt: 1710000060000,
+      });
+      await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "strava",
+        idempotencyKey: "job-5",
+        status: "completed",
+        startedAt: 1710100000000,
+        completedAt: 1710100060000,
+      });
+      await ctx.db.insert("syncJobs", {
+        connectionId: otherConnectionId,
+        userId: "user-2",
+        provider: "garmin",
+        idempotencyKey: "job-6",
+        status: "completed",
+        startedAt: 1710000000000,
+      });
+    });
+
+    const user1Jobs = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("syncJobs")
+        .withIndex("by_user", (idx) => idx.eq("userId", "user-1"))
+        .order("desc")
+        .collect();
+    });
+
+    expect(user1Jobs).toHaveLength(2);
+  });
+
+  it("queries running jobs via status index", async () => {
+    const t = convexTest(schema, modules);
+    const connectionId = await seedConnection(t);
+    const otherConnectionId = await seedConnection(t, { userId: "user-2" });
+    const thirdConnectionId = await seedConnection(t, {
+      userId: "user-3",
+      provider: "garmin",
+    });
+
+    await t.run(async (ctx) => {
+      await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "strava",
+        idempotencyKey: "job-7",
+        status: "running",
+        startedAt: Date.now(),
+      });
+      await ctx.db.insert("syncJobs", {
+        connectionId: otherConnectionId,
+        userId: "user-2",
+        provider: "strava",
+        idempotencyKey: "job-8",
+        status: "completed",
+        startedAt: Date.now(),
+      });
+      await ctx.db.insert("syncJobs", {
+        connectionId: thirdConnectionId,
+        userId: "user-3",
+        provider: "garmin",
+        idempotencyKey: "job-9",
+        status: "running",
+        startedAt: Date.now(),
+      });
+    });
+
+    const running = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("syncJobs")
+        .withIndex("by_status", (idx) => idx.eq("status", "running"))
+        .collect();
+    });
+
+    expect(running).toHaveLength(2);
+  });
+
+  it("queries by user + status via composite index", async () => {
+    const t = convexTest(schema, modules);
+    const connectionId = await seedConnection(t);
+
+    await t.run(async (ctx) => {
+      await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "strava",
+        idempotencyKey: "job-10",
+        status: "completed",
+        startedAt: Date.now(),
+      });
+      await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "strava",
+        idempotencyKey: "job-11",
+        status: "failed",
+        startedAt: Date.now(),
+        error: "timeout",
+      });
+      await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "strava",
+        idempotencyKey: "job-12",
+        status: "running",
+        startedAt: Date.now(),
+      });
+    });
+
+    const failedJobs = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("syncJobs")
+        .withIndex("by_user_status", (idx) => idx.eq("userId", "user-1").eq("status", "failed"))
+        .collect();
+    });
+
+    expect(failedJobs).toHaveLength(1);
+    expect(failedJobs[0].error).toBe("timeout");
+  });
+});

package/src/component/syncJobs.ts

@@ -0,0 +1,140 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery, query } from "./_generated/server";
+import { providerName, syncJobStatus } from "./schema";
+
+const syncPhase = v.union(v.literal("events"), v.literal("dataPoints"), v.literal("summaries"));
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+export const getByUser = query({
+  args: {
+    userId: v.string(),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(v.any()),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("syncJobs")
+      .withIndex("by_user", (idx) => idx.eq("userId", args.userId))
+      .order("desc")
+      .take(args.limit ?? 10);
+  },
+});
+
+export const getRunning = internalQuery({
+  args: {},
+  returns: v.array(v.any()),
+  handler: async (ctx) => {
+    return await ctx.db
+      .query("syncJobs")
+      .withIndex("by_status", (idx) => idx.eq("status", "running"))
+      .collect();
+  },
+});
+
+export const getById = internalQuery({
+  args: {
+    jobId: v.id("syncJobs"),
+  },
+  returns: v.union(v.any(), v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.jobId);
+  },
+});
+
+export const getActiveByIdempotencyKey = internalQuery({
+  args: {
+    idempotencyKey: v.string(),
+  },
+  returns: v.union(v.any(), v.null()),
+  handler: async (ctx, args) => {
+    const job = await ctx.db
+      .query("syncJobs")
+      .withIndex("by_idempotency_key", (idx) => idx.eq("idempotencyKey", args.idempotencyKey))
+      .order("desc")
+      .first();
+
+    if (!job) {
+      return null;
+    }
+
+    return job.status === "queued" || job.status === "running" ? job : null;
+  },
+});
+
+export const getByWorkflowId = internalQuery({
+  args: {
+    workflowId: v.string(),
+  },
+  returns: v.union(v.any(), v.null()),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("syncJobs")
+      .withIndex("by_workflow", (idx) => idx.eq("workflowId", args.workflowId))
+      .first();
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Mutations
+// ---------------------------------------------------------------------------
+
+export const create = internalMutation({
+  args: {
+    connectionId: v.id("connections"),
+    userId: v.string(),
+    provider: providerName,
+    mode: v.optional(v.union(v.literal("manual"), v.literal("cron"), v.literal("webhook"))),
+    triggerSource: v.optional(v.string()),
+    idempotencyKey: v.string(),
+    startedAt: v.optional(v.number()),
+    windowStart: v.optional(v.number()),
+    windowEnd: v.optional(v.number()),
+  },
+  returns: v.id("syncJobs"),
+  handler: async (ctx, args) => {
+    return await ctx.db.insert("syncJobs", {
+      connectionId: args.connectionId,
+      userId: args.userId,
+      provider: args.provider,
+      mode: args.mode,
+      triggerSource: args.triggerSource,
+      idempotencyKey: args.idempotencyKey,
+      status: "queued",
+      startedAt: args.startedAt ?? Date.now(),
+      windowStart: args.windowStart,
+      windowEnd: args.windowEnd,
+      attempt: 0,
+    });
+  },
+});
+
+export const updateStatus = internalMutation({
+  args: {
+    jobId: v.id("syncJobs"),
+    status: syncJobStatus,
+    error: v.optional(v.string()),
+    recordsProcessed: v.optional(v.number()),
+    workflowId: v.optional(v.string()),
+    attempt: v.optional(v.number()),
+    lastHeartbeatAt: v.optional(v.number()),
+    cursor: v.optional(v.string()),
+    currentPhase: v.optional(syncPhase),
+  },
+  handler: async (ctx, args) => {
+    const updates: Record<string, unknown> = { status: args.status };
+    if (args.error !== undefined) updates.error = args.error;
+    if (args.recordsProcessed !== undefined) updates.recordsProcessed = args.recordsProcessed;
+    if (args.workflowId !== undefined) updates.workflowId = args.workflowId;
+    if (args.attempt !== undefined) updates.attempt = args.attempt;
+    if (args.lastHeartbeatAt !== undefined) updates.lastHeartbeatAt = args.lastHeartbeatAt;
+    if (args.cursor !== undefined) updates.cursor = args.cursor;
+    if (args.currentPhase !== undefined) updates.currentPhase = args.currentPhase;
+    if (args.status === "completed" || args.status === "failed" || args.status === "canceled") {
+      updates.completedAt = Date.now();
+    }
+    await ctx.db.patch(args.jobId, updates);
+  },
+});

package/src/component/syncWorkflow.test.ts

@@ -0,0 +1,87 @@
+import workflowTest from "@convex-dev/workflow/test";
+import workpoolTest from "@convex-dev/workpool/test";
+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";
+
+function createWorkflowTest() {
+  const t = convexTest(schema, modules);
+  t.registerComponent("workflow", workflowTest.schema, workflowTest.modules);
+  workpoolTest.register(t, "workflow/workpool");
+  return t;
+}
+
+describe("syncWorkflow", () => {
+  it("reuses an active sync job with the same idempotency key", async () => {
+    const t = createWorkflowTest();
+
+    const connectionId = await t.run(async (ctx) => {
+      return await ctx.db.insert("connections", {
+        userId: "user-1",
+        provider: "garmin",
+        accessToken: "garmin-token",
+        tokenExpiresAt: Date.now() + 60_000,
+        status: "active",
+      });
+    });
+
+    const existingJobId = await t.run(async (ctx) => {
+      return await ctx.db.insert("syncJobs", {
+        connectionId,
+        userId: "user-1",
+        provider: "garmin",
+        idempotencyKey: `${connectionId}::manual::1000::2000`,
+        status: "queued",
+        startedAt: Date.now(),
+      });
+    });
+
+    const result = await t.mutation(internal.syncWorkflow.requestConnectionSync, {
+      connectionId,
+      mode: "manual",
+      triggerSource: "test",
+      windowStart: 1000,
+      windowEnd: 2000,
+    });
+
+    expect(String(result.syncJobId)).toBe(String(existingJobId));
+    expect(result.deduped).toBe(true);
+  });
+
+  it("enqueues a garmin sync on the durable workflow", async () => {
+    const t = createWorkflowTest();
+
+    const connectionId = await t.run(async (ctx) => {
+      return await ctx.db.insert("connections", {
+        userId: "user-1",
+        provider: "garmin",
+        accessToken: "garmin-token",
+        tokenExpiresAt: Date.now() + 60 * 60 * 1000,
+        status: "active",
+      });
+    });
+
+    await t.mutation(internal.providerSettings.upsertCredentials, {
+      provider: "garmin",
+      clientId: "garmin-client",
+      clientSecret: "garmin-secret",
+    });
+
+    const result = await t.action(api.syncWorkflow.syncConnection, {
+      connectionId,
+      provider: "garmin",
+      clientId: "garmin-client",
+      clientSecret: "garmin-secret",
+    });
+
+    const job = await t.query(internal.syncJobs.getById, {
+      jobId: result.syncJobId as never,
+    });
+
+    expect(job?.status).toBe("queued");
+    expect(job?.workflowId).toBeDefined();
+    expect(result.deduped).toBe(false);
+  });
+});