@nativesquare/soma 0.16.4 → 0.16.6

package/src/component/public.ts

@@ -1,6 +1,7 @@
 import { paginationOptsValidator } from "convex/server";
 import { v } from "convex/values";
 import { mutation, query } from "./_generated/server.js";
+import type { Id } from "./_generated/dataModel.js";
 import { activityValidator } from "./validators/activity.js";
 import { athleteValidator } from "./validators/athlete.js";
 import { bodyValidator } from "./validators/body.js";
@@ -9,6 +10,8 @@ import { sleepValidator } from "./validators/sleep.js";
 import { menstruationValidator } from "./validators/menstruation.js";
 import { nutritionValidator } from "./validators/nutrition.js";
 import { plannedWorkoutValidator } from "./validators/plannedWorkout.js";
+import { statsValidator } from "./validators/connection.js";
+import { normalizeStats, updateStatsOnIngest } from "./utils.js";
 
 // ─── Return Validators ──────────────────────────────────────────────────────
 
@@ -20,6 +23,7 @@ const connectionDoc = v.object({
   providerUserId: v.optional(v.string()),
   active: v.optional(v.boolean()),
   lastDataUpdate: v.optional(v.string()),
+  stats: v.optional(statsValidator),
 });
 
 // ─── Connect / Disconnect ───────────────────────────────────────────────────
@@ -130,6 +134,41 @@ export const getConnectionByProvider = query({
   },
 });
 
+/**
+ * Get per-table row counts and oldest-data timestamps for a user–provider pair.
+ *
+ * Stats are denormalized onto the connection document and maintained
+ * automatically by ingest mutations, so this is an O(1) read regardless of
+ * how much data has been ingested.
+ *
+ * `oldest` is a lower bound on the earliest `metadata.start_time` (or
+ * `metadata.planned_date` for planned workouts). It can theoretically go
+ * stale if a provider mutates `start_time` on an existing record to a later
+ * value — this would also break the existing dedup strategy, so treat it as
+ * pathological.
+ *
+ * Returns `null` if the user has never connected to that provider. When a
+ * connection exists but no data has been ingested, every table returns
+ * `{ count: 0, oldest: null }` — callers never need to guard optional keys.
+ */
+export const getProviderStats = query({
+  args: {
+    userId: v.string(),
+    provider: v.string(),
+  },
+  returns: v.union(v.null(), statsValidator),
+  handler: async (ctx, args) => {
+    const connection = await ctx.db
+      .query("connections")
+      .withIndex("by_userId_provider", (q) =>
+        q.eq("userId", args.userId).eq("provider", args.provider),
+      )
+      .first();
+    if (!connection) return null;
+    return normalizeStats(connection.stats);
+  },
+});
+
 /**
  * List all connections for a user (active and inactive).
  */
@@ -212,11 +251,21 @@ export const ingestActivity = mutation({
       )
       .first();
 
+    let id: Id<"activities">;
     if (existing) {
       await ctx.db.patch(existing._id, args);
-      return existing._id;
+      id = existing._id;
+    } else {
+      id = await ctx.db.insert("activities", args);
     }
-    return await ctx.db.insert("activities", args);
+    await updateStatsOnIngest(
+      ctx,
+      args.connectionId,
+      "activities",
+      args.metadata.start_time,
+      !existing,
+    );
+    return id;
   },
 });
 
@@ -231,8 +280,9 @@ export const ingestSleep = mutation({
   returns: v.id("sleep"),
   handler: async (ctx, args) => {
     const summaryId = args.metadata.summary_id;
+    let existing: { _id: Id<"sleep"> } | null = null;
     if (summaryId) {
-      const existing = await ctx.db
+      existing = await ctx.db
         .query("sleep")
         .withIndex("by_connectionId_summaryId", (q) =>
           q
@@ -240,13 +290,23 @@ export const ingestSleep = mutation({
             .eq("metadata.summary_id", summaryId),
         )
         .first();
+    }
 
-      if (existing) {
-        await ctx.db.patch(existing._id, args);
-        return existing._id;
-      }
+    let id: Id<"sleep">;
+    if (existing) {
+      await ctx.db.patch(existing._id, args);
+      id = existing._id;
+    } else {
+      id = await ctx.db.insert("sleep", args);
     }
-    return await ctx.db.insert("sleep", args);
+    await updateStatsOnIngest(
+      ctx,
+      args.connectionId,
+      "sleep",
+      args.metadata.start_time,
+      !existing,
+    );
+    return id;
   },
 });
 
@@ -269,11 +329,21 @@ export const ingestBody = mutation({
       )
       .first();
 
+    let id: Id<"body">;
     if (existing) {
       await ctx.db.patch(existing._id, args);
-      return existing._id;
+      id = existing._id;
+    } else {
+      id = await ctx.db.insert("body", args);
     }
-    return await ctx.db.insert("body", args);
+    await updateStatsOnIngest(
+      ctx,
+      args.connectionId,
+      "body",
+      args.metadata.start_time,
+      !existing,
+    );
+    return id;
   },
 });
 
@@ -296,11 +366,21 @@ export const ingestDaily = mutation({
       )
       .first();
 
+    let id: Id<"daily">;
     if (existing) {
       await ctx.db.patch(existing._id, args);
-      return existing._id;
+      id = existing._id;
+    } else {
+      id = await ctx.db.insert("daily", args);
     }
-    return await ctx.db.insert("daily", args);
+    await updateStatsOnIngest(
+      ctx,
+      args.connectionId,
+      "daily",
+      args.metadata.start_time,
+      !existing,
+    );
+    return id;
   },
 });
 
@@ -323,11 +403,21 @@ export const ingestNutrition = mutation({
       )
       .first();
 
+    let id: Id<"nutrition">;
     if (existing) {
       await ctx.db.patch(existing._id, args);
-      return existing._id;
+      id = existing._id;
+    } else {
+      id = await ctx.db.insert("nutrition", args);
     }
-    return await ctx.db.insert("nutrition", args);
+    await updateStatsOnIngest(
+      ctx,
+      args.connectionId,
+      "nutrition",
+      args.metadata.start_time,
+      !existing,
+    );
+    return id;
   },
 });
 
@@ -340,7 +430,15 @@ export const ingestMenstruation = mutation({
   args: menstruationValidator,
   returns: v.id("menstruation"),
   handler: async (ctx, args) => {
-    return await ctx.db.insert("menstruation", args);
+    const id = await ctx.db.insert("menstruation", args);
+    await updateStatsOnIngest(
+      ctx,
+      args.connectionId,
+      "menstruation",
+      args.metadata.start_time,
+      true,
+    );
+    return id;
   },
 });
 
@@ -799,6 +897,7 @@ export const ingestPlannedWorkout = mutation({
   returns: v.id("plannedWorkouts"),
   handler: async (ctx, args) => {
     const metadataId = args.metadata.id;
+    let existing: { _id: Id<"plannedWorkouts"> } | null = null;
     if (metadataId) {
       const results = await ctx.db
         .query("plannedWorkouts")
@@ -806,14 +905,24 @@ export const ingestPlannedWorkout = mutation({
           q.eq("connectionId", args.connectionId),
         )
         .collect();
-      const existing = results.find((r) => r.metadata.id === metadataId);
+      existing = results.find((r) => r.metadata.id === metadataId) ?? null;
+    }
 
-      if (existing) {
-        await ctx.db.patch(existing._id, args);
-        return existing._id;
-      }
+    let id: Id<"plannedWorkouts">;
+    if (existing) {
+      await ctx.db.patch(existing._id, args);
+      id = existing._id;
+    } else {
+      id = await ctx.db.insert("plannedWorkouts", args);
     }
-    return await ctx.db.insert("plannedWorkouts", args);
+    await updateStatsOnIngest(
+      ctx,
+      args.connectionId,
+      "plannedWorkouts",
+      args.metadata.planned_date,
+      !existing,
+    );
+    return id;
   },
 });
 

package/src/component/utils.ts

@@ -1,22 +1,116 @@
-// ─── Shared Helpers ─────────────────────────────────────────────────────────
-// Provider-agnostic utilities shared across providers (Strava, Garmin, etc.).
-
-/**
- * Normalized result from any provider's OAuth refresh-token call.
- * Each provider's `refreshToken` maps its raw API response into this shape.
- */
-export interface OAuthRefreshResult {
-  access_token: string;
-  refresh_token: string;
-  /** Absolute Unix timestamp (seconds) when the access token expires. */
-  expiresAt: number;
-}
-
-/**
- * Generate a random state parameter for CSRF protection.
- */
-export function generateState(): string {
-  const bytes = new Uint8Array(32);
-  crypto.getRandomValues(bytes);
-  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
-}
+// ─── Shared Helpers ─────────────────────────────────────────────────────────
+// Provider-agnostic utilities shared across providers (Strava, Garmin, etc.).
+
+import type { MutationCtx } from "./_generated/server.js";
+import type { Id } from "./_generated/dataModel.js";
+
+/**
+ * Normalized result from any provider's OAuth refresh-token call.
+ * Each provider's `refreshToken` maps its raw API response into this shape.
+ */
+export interface OAuthRefreshResult {
+  access_token: string;
+  refresh_token: string;
+  /** Absolute Unix timestamp (seconds) when the access token expires. */
+  expiresAt: number;
+}
+
+/**
+ * Generate a random state parameter for CSRF protection.
+ */
+export function generateState(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+// ─── Connection Stats ───────────────────────────────────────────────────────
+
+export type StatsTable =
+  | "activities"
+  | "sleep"
+  | "body"
+  | "daily"
+  | "nutrition"
+  | "menstruation"
+  | "plannedWorkouts";
+
+export interface StatsEntry {
+  count: number;
+  oldest: string | null;
+}
+
+export type ConnectionStats = Record<StatsTable, StatsEntry>;
+
+const STATS_TABLES: readonly StatsTable[] = [
+  "activities",
+  "sleep",
+  "body",
+  "daily",
+  "nutrition",
+  "menstruation",
+  "plannedWorkouts",
+];
+
+export function defaultStats(): ConnectionStats {
+  return {
+    activities: { count: 0, oldest: null },
+    sleep: { count: 0, oldest: null },
+    body: { count: 0, oldest: null },
+    daily: { count: 0, oldest: null },
+    nutrition: { count: 0, oldest: null },
+    menstruation: { count: 0, oldest: null },
+    plannedWorkouts: { count: 0, oldest: null },
+  };
+}
+
+/**
+ * Fill in any missing sub-objects with zeroed defaults so callers always
+ * see every table key populated.
+ */
+export function normalizeStats(
+  stats: Partial<ConnectionStats> | undefined,
+): ConnectionStats {
+  const base = defaultStats();
+  if (!stats) return base;
+  for (const t of STATS_TABLES) {
+    const entry = stats[t];
+    if (entry) base[t] = { count: entry.count, oldest: entry.oldest };
+  }
+  return base;
+}
+
+/**
+ * Update the denormalized stats on a connection after an ingest mutation.
+ *
+ * On a new insert: increment `count` and min-check `oldest`.
+ * On an upsert (existing row): only min-check `oldest` — in case the provider
+ * supplied an earlier `start_time` than what was first ingested.
+ *
+ * No-ops if the connection row is missing, so ingests remain resilient against
+ * dangling connectionIds. Safe under concurrent ingests: Convex mutations are
+ * serializable (OCC with retry), so parallel patches on the same connection
+ * do not race.
+ */
+export async function updateStatsOnIngest(
+  ctx: MutationCtx,
+  connectionId: Id<"connections">,
+  table: StatsTable,
+  oldestCandidate: string | undefined,
+  isNewInsert: boolean,
+): Promise<void> {
+  const connection = await ctx.db.get(connectionId);
+  if (!connection) return;
+
+  const next = normalizeStats(connection.stats);
+  const sub = { ...next[table] };
+  if (isNewInsert) sub.count += 1;
+  if (oldestCandidate !== undefined) {
+    sub.oldest =
+      sub.oldest === null || oldestCandidate < sub.oldest
+        ? oldestCandidate
+        : sub.oldest;
+  }
+  next[table] = sub;
+  await ctx.db.patch(connectionId, { stats: next });
+}

package/src/component/validators/connection.ts

@@ -4,6 +4,21 @@ import { v } from "convex/values";
 // Represents a link between a host app user and a wearable provider.
 // Provider-agnostic: Soma doesn't care if data comes via Terra, direct API, etc.
 // One document per user-provider pair.
+const statsEntryValidator = v.object({
+  count: v.number(),
+  oldest: v.union(v.string(), v.null()),
+});
+
+export const statsValidator = v.object({
+  activities: statsEntryValidator,
+  sleep: statsEntryValidator,
+  body: statsEntryValidator,
+  daily: statsEntryValidator,
+  nutrition: statsEntryValidator,
+  menstruation: statsEntryValidator,
+  plannedWorkouts: statsEntryValidator,
+});
+
 export const connectionValidator = {
   // Host app's user identifier (their user ID, Clerk ID, etc.)
   userId: v.string(),
@@ -15,4 +30,7 @@ export const connectionValidator = {
   active: v.optional(v.boolean()),
   // ISO-8601 timestamp of last data update
   lastDataUpdate: v.optional(v.string()),
+  // Per-table denormalized counters maintained by ingest mutations.
+  // `oldest` is the earliest metadata.start_time (or planned_date) observed.
+  stats: v.optional(statsValidator),
 };

package/src/component/validators/shared.ts

@@ -26,6 +26,7 @@ export type SomaErrorType =
   // Operation types
   | "deleteSchedule"
   | "deleteWorkout"
+  | "deregistration"
   | "ingest"
   | "pushSchedule"
   | "pushWorkout";