@nativesquare/soma 0.1.0

package/dist/healthkit/utils.js

@@ -0,0 +1,93 @@
+// ─── Shared Utilities ────────────────────────────────────────────────────────
+// Pure helper functions used across HealthKit transformer modules.
+/**
+ * Compute the difference in seconds between two ISO-8601 timestamps.
+ */
+export function diffSeconds(start, end) {
+    return (new Date(end).getTime() - new Date(start).getTime()) / 1000;
+}
+/**
+ * Build the start-of-day and end-of-day ISO-8601 strings for a date.
+ */
+export function dayRange(date) {
+    const pad = (n) => String(n).padStart(2, "0");
+    const dateStr = `${date.year}-${pad(date.month)}-${pad(date.day)}`;
+    return {
+        start_time: `${dateStr}T00:00:00.000Z`,
+        end_time: `${dateStr}T23:59:59.999Z`,
+    };
+}
+/**
+ * Find the earliest startDate and latest endDate in an array of samples.
+ * Returns ISO-8601 strings. Falls back to provided defaults if array is empty.
+ */
+export function sampleTimeRange(samples, fallback) {
+    if (samples.length === 0) {
+        return (fallback ?? {
+            start_time: new Date().toISOString(),
+            end_time: new Date().toISOString(),
+        });
+    }
+    let minStart = samples[0].startDate;
+    let maxEnd = samples[0].endDate;
+    for (const s of samples) {
+        if (s.startDate < minStart)
+            minStart = s.startDate;
+        if (s.endDate > maxEnd)
+            maxEnd = s.endDate;
+    }
+    return { start_time: minStart, end_time: maxEnd };
+}
+/**
+ * Build a Soma DeviceData object from HealthKit source and device metadata.
+ */
+export function buildDeviceData(source, device) {
+    if (!source && !device)
+        return undefined;
+    return {
+        name: device?.name ?? source?.name,
+        manufacturer: device?.manufacturer,
+        hardware_version: device?.hardwareVersion,
+        software_version: device?.softwareVersion,
+    };
+}
+/**
+ * Filter an array of HKQuantitySamples by sampleType identifier.
+ */
+export function filterByType(samples, sampleType) {
+    return samples.filter((s) => s.sampleType === sampleType);
+}
+/**
+ * Sum the values of quantity samples.
+ */
+export function sumValues(samples) {
+    return samples.reduce((acc, s) => acc + s.value, 0);
+}
+/**
+ * Average the values of quantity samples.
+ * Returns undefined if the array is empty.
+ */
+export function avgValue(samples) {
+    if (samples.length === 0)
+        return undefined;
+    return sumValues(samples) / samples.length;
+}
+/**
+ * Min value in a set of quantity samples.
+ * Returns undefined if the array is empty.
+ */
+export function minValue(samples) {
+    if (samples.length === 0)
+        return undefined;
+    return Math.min(...samples.map((s) => s.value));
+}
+/**
+ * Max value in a set of quantity samples.
+ * Returns undefined if the array is empty.
+ */
+export function maxValue(samples) {
+    if (samples.length === 0)
+        return undefined;
+    return Math.max(...samples.map((s) => s.value));
+}
+//# sourceMappingURL=utils.js.map

package/dist/healthkit/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/healthkit/utils.ts"],"names":[],"mappings":"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"}

package/dist/react/index.d.ts

@@ -0,0 +1,2 @@
+export declare const useMyComponent: () => {};
+//# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,cAAc,UAE1B,CAAC"}

package/dist/react/index.js

@@ -0,0 +1,6 @@
+"use client";
+// This is where React components / hooks go.
+export const useMyComponent = () => {
+    return {};
+};
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,6CAA6C;AAE7C,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,EAAE;IACjC,OAAO,EAAE,CAAC;AACZ,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,112 @@
+{
+  "name": "@nativesquare/soma",
+  "description": "A Convex component that normalizes health and fitness data from multiple wearable providers into a single, consistent schema.",
+  "repository": "github:NativeSquare/soma",
+  "homepage": "https://github.com/NativeSquare/soma#readme",
+  "bugs": {
+    "url": "https://github.com/NativeSquare/soma/issues"
+  },
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "keywords": [
+    "convex",
+    "component"
+  ],
+  "type": "module",
+  "scripts": {
+    "dev": "run-p -r dev:*",
+    "dev:backend": "convex dev --typecheck-components",
+    "dev:frontend": "cd example && vite --clearScreen false",
+    "dev:build": "chokidar \"tsconfig*.json\" \"src/**/*.ts\" -i \"**/*.test.ts\" -c \"npm run build:codegen\" --initial",
+    "predev": "path-exists .env.local dist || (npm run build && convex dev --once)",
+    "build": "tsc --project ./tsconfig.build.json",
+    "build:codegen": "npx convex codegen --component-dir ./src/component && npm run build",
+    "build:clean": "npx rimraf dist *.tsbuildinfo && npm run build:codegen",
+    "typecheck": "tsc --noEmit && tsc -p example && tsc -p example/convex",
+    "lint": "eslint .",
+    "all": "run-p -r dev:* test:watch",
+    "test": "vitest run --typecheck",
+    "test:watch": "vitest --typecheck --clearScreen false",
+    "test:debug": "vitest --inspect-brk --no-file-parallelism",
+    "test:coverage": "vitest run --coverage --coverage.reporter=text",
+    "preversion": "npm ci && npm run build:clean && run-p test lint typecheck",
+    "prepublishOnly": "npm whoami || npm login",
+    "alpha": "npm version prerelease --preid alpha && npm publish --tag alpha && git push --follow-tags",
+    "release": "npm version patch && npm publish && git push --follow-tags",
+    "version": "vim -c 'normal o' -c 'normal o## '$npm_package_version CHANGELOG.md && prettier -w CHANGELOG.md && git add CHANGELOG.md"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./healthkit": {
+      "types": "./dist/healthkit/index.d.ts",
+      "default": "./dist/healthkit/index.js"
+    },
+    "./test": "./src/test.ts",
+    "./_generated/component.js": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./_generated/component": {
+      "types": "./dist/component/_generated/component.d.ts"
+    },
+    "./convex.config.js": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    },
+    "./convex.config": {
+      "types": "./dist/component/convex.config.d.ts",
+      "default": "./dist/component/convex.config.js"
+    }
+  },
+  "peerDependencies": {
+    "convex": "^1.31.7",
+    "react": "^18.3.1 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@convex-dev/eslint-plugin": "^1.1.1",
+    "@edge-runtime/vm": "^5.0.0",
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "9.39.2",
+    "@types/node": "^24.10.11",
+    "@types/react": "^19.2.13",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.3",
+    "chokidar-cli": "3.0.0",
+    "convex": "1.31.7",
+    "convex-test": "0.0.41",
+    "eslint": "9.39.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.5.0",
+    "globals": "^17.3.0",
+    "npm-run-all2": "8.0.4",
+    "path-exists-cli": "2.0.0",
+    "pkg-pr-new": "^0.0.63",
+    "prettier": "3.8.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.54.0",
+    "vite": "7.3.1",
+    "vitest": "4.0.18"
+  },
+  "types": "./dist/client/index.d.ts",
+  "module": "./dist/client/index.js",
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "@tailwindcss/oxide"
+    ]
+  }
+}

package/src/client/_generated/_ignore.ts

@@ -0,0 +1 @@
+// This is only here so convex-test can detect a _generated folder

package/src/client/index.ts

@@ -0,0 +1,371 @@
+import type { ComponentApi } from "../component/_generated/component.js";
+import type { MutationCtx, QueryCtx } from "./types.js";
+
+export type SomaComponent = ComponentApi;
+
+/**
+ * Client class for the @nativesquare/soma Convex component.
+ *
+ * Provides a type-safe interface for managing wearable provider connections
+ * and querying normalized health & fitness data.
+ *
+ * All capabilities are also accessible via direct component function calls:
+ * `ctx.runMutation(components.soma.public.connect, { userId, provider: "GARMIN" })`
+ *
+ * @example
+ * ```ts
+ * // In your Convex function file:
+ * import { Soma } from "@nativesquare/soma";
+ * import { components } from "./_generated/api";
+ *
+ * const soma = new Soma(components.soma);
+ *
+ * // Connect a user to a provider:
+ * const connectionId = await soma.connect(ctx, {
+ *   userId: "user_123",
+ *   provider: "GARMIN",
+ * });
+ *
+ * // List all connections:
+ * const connections = await soma.listConnections(ctx, { userId: "user_123" });
+ * ```
+ */
+export class Soma {
+  constructor(public component: SomaComponent) { }
+
+  // ─── Connect / Disconnect ───────────────────────────────────────────────────
+
+  /**
+   * Connect a user to a wearable provider.
+   *
+   * Creates the connection if it doesn't exist, or re-activates it if it was
+   * previously disconnected. Idempotent — calling twice is a no-op.
+   *
+   * Use this when the host app has completed the provider's auth flow and
+   * wants to register the connection in Soma.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args.userId - The host app's user identifier (Clerk ID, etc.)
+   * @param args.provider - The wearable provider name ("GARMIN", "FITBIT", "OURA", etc.)
+   * @returns The connection document ID
+   *
+   * @example
+   * ```ts
+   * // "Connect to Garmin" button handler
+   * const connectionId = await soma.connect(ctx, {
+   *   userId: "user_123",
+   *   provider: "GARMIN",
+   * });
+   * ```
+   */
+  async connect(
+    ctx: MutationCtx,
+    args: { userId: string; provider: string },
+  ): Promise<string> {
+    return await ctx.runMutation(this.component.public.connect, args);
+  }
+
+  /**
+   * Disconnect a user from a wearable provider.
+   *
+   * Sets the connection to inactive. Does not delete any synced data,
+   * so re-connecting later preserves historical records.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.provider - The wearable provider name
+   *
+   * @throws Error if no connection exists for the given user–provider pair
+   *
+   * @example
+   * ```ts
+   * // "Disconnect Garmin" button handler
+   * await soma.disconnect(ctx, {
+   *   userId: "user_123",
+   *   provider: "GARMIN",
+   * });
+   * ```
+   */
+  async disconnect(
+    ctx: MutationCtx,
+    args: { userId: string; provider: string },
+  ): Promise<null> {
+    return await ctx.runMutation(this.component.public.disconnect, args);
+  }
+
+  // ─── Connection Queries ─────────────────────────────────────────────────────
+
+  /**
+   * Get a connection by its document ID.
+   *
+   * @param ctx - Query context from the host app
+   * @param args.connectionId - The connection document ID
+   * @returns The connection document, or null if not found
+   */
+  async getConnection(
+    ctx: QueryCtx,
+    args: { connectionId: string },
+  ) {
+    return await ctx.runQuery(this.component.public.getConnection, args);
+  }
+
+  /**
+   * Get the connection for a specific user–provider pair.
+   *
+   * Useful for checking whether a user is connected to a specific provider
+   * (e.g., rendering a "Connected" badge on a provider card).
+   *
+   * @param ctx - Query context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.provider - The wearable provider name
+   * @returns The connection document, or null if never connected
+   *
+   * @example
+   * ```ts
+   * const garmin = await soma.getConnectionByProvider(ctx, {
+   *   userId: "user_123",
+   *   provider: "GARMIN",
+   * });
+   * const isConnected = garmin?.active === true;
+   * ```
+   */
+  async getConnectionByProvider(
+    ctx: QueryCtx,
+    args: { userId: string; provider: string },
+  ) {
+    return await ctx.runQuery(
+      this.component.public.getConnectionByProvider,
+      args,
+    );
+  }
+
+  /**
+   * List all connections for a user (active and inactive).
+   *
+   * @param ctx - Query context from the host app
+   * @param args.userId - The host app's user identifier
+   * @returns Array of connection documents
+   *
+   * @example
+   * ```ts
+   * const connections = await soma.listConnections(ctx, { userId: "user_123" });
+   * const activeProviders = connections
+   *   .filter(c => c.active)
+   *   .map(c => c.provider);
+   * ```
+   */
+  async listConnections(
+    ctx: QueryCtx,
+    args: { userId: string },
+  ) {
+    return await ctx.runQuery(this.component.public.listConnections, args);
+  }
+
+  // ─── Connection Mutations ───────────────────────────────────────────────────
+
+  /**
+   * Update a connection's mutable fields.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args.connectionId - The connection document ID
+   * @param args.active - Optional new active status
+   * @param args.lastDataUpdate - Optional ISO-8601 timestamp of last data sync
+   *
+   * @throws Error if the connection does not exist
+   */
+  async updateConnection(
+    ctx: MutationCtx,
+    args: {
+      connectionId: string;
+      active?: boolean;
+      lastDataUpdate?: string;
+    },
+  ): Promise<null> {
+    return await ctx.runMutation(
+      this.component.public.updateConnection,
+      args,
+    );
+  }
+
+  /**
+   * Delete a connection record entirely.
+   *
+   * This is a hard delete — the connection row is removed.
+   * Synced health data linked to this connection is NOT cascade-deleted.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args.connectionId - The connection document ID
+   *
+   * @throws Error if the connection does not exist
+   */
+  async deleteConnection(
+    ctx: MutationCtx,
+    args: { connectionId: string },
+  ): Promise<null> {
+    return await ctx.runMutation(
+      this.component.public.deleteConnection,
+      args,
+    );
+  }
+
+  // ─── Data Ingestion ─────────────────────────────────────────────────────────
+  // Store normalized health data into Soma with automatic deduplication.
+  // Use with transformer functions from @nativesquare/soma/healthkit:
+  //
+  //   import { transformWorkout } from "@nativesquare/soma/healthkit";
+  //   const data = transformWorkout(hkWorkout);
+  //   await soma.ingestActivity(ctx, { connectionId, userId, ...data });
+
+  /**
+   * Ingest an activity (workout) record.
+   *
+   * Upserts by `connectionId + metadata.summary_id` — re-ingesting the same
+   * workout updates the existing record rather than creating a duplicate.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args - Activity data including connectionId, userId, metadata, and all activity fields
+   * @returns The activity document ID
+   *
+   * @example
+   * ```ts
+   * import { transformWorkout } from "@nativesquare/soma/healthkit";
+   * const data = transformWorkout(hkWorkout);
+   * const id = await soma.ingestActivity(ctx, { connectionId, userId, ...data });
+   * ```
+   */
+  async ingestActivity(
+    ctx: MutationCtx,
+    args: IngestArgs,
+  ): Promise<string> {
+    return await ctx.runMutation(
+      this.component.public.ingestActivity,
+      args as never,
+    );
+  }
+
+  /**
+   * Ingest a sleep session record.
+   *
+   * Upserts by `connectionId + metadata.summary_id`.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args - Sleep data including connectionId, userId, metadata, and all sleep fields
+   * @returns The sleep document ID
+   */
+  async ingestSleep(
+    ctx: MutationCtx,
+    args: IngestArgs,
+  ): Promise<string> {
+    return await ctx.runMutation(
+      this.component.public.ingestSleep,
+      args as never,
+    );
+  }
+
+  /**
+   * Ingest a body metrics record.
+   *
+   * Upserts by `connectionId + metadata.start_time + metadata.end_time`.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args - Body data including connectionId, userId, metadata, and all body fields
+   * @returns The body document ID
+   */
+  async ingestBody(
+    ctx: MutationCtx,
+    args: IngestArgs,
+  ): Promise<string> {
+    return await ctx.runMutation(
+      this.component.public.ingestBody,
+      args as never,
+    );
+  }
+
+  /**
+   * Ingest a daily activity summary record.
+   *
+   * Upserts by `connectionId + metadata.start_time + metadata.end_time`.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args - Daily data including connectionId, userId, metadata, and all daily fields
+   * @returns The daily document ID
+   */
+  async ingestDaily(
+    ctx: MutationCtx,
+    args: IngestArgs,
+  ): Promise<string> {
+    return await ctx.runMutation(
+      this.component.public.ingestDaily,
+      args as never,
+    );
+  }
+
+  /**
+   * Ingest a nutrition record.
+   *
+   * Upserts by `connectionId + metadata.start_time + metadata.end_time`.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args - Nutrition data including connectionId, userId, metadata, and all nutrition fields
+   * @returns The nutrition document ID
+   */
+  async ingestNutrition(
+    ctx: MutationCtx,
+    args: IngestArgs,
+  ): Promise<string> {
+    return await ctx.runMutation(
+      this.component.public.ingestNutrition,
+      args as never,
+    );
+  }
+
+  /**
+   * Ingest a menstruation record.
+   *
+   * Append-only — each call creates a new document.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args - Menstruation data including connectionId, userId, metadata, and menstruation fields
+   * @returns The menstruation document ID
+   */
+  async ingestMenstruation(
+    ctx: MutationCtx,
+    args: IngestArgs,
+  ): Promise<string> {
+    return await ctx.runMutation(
+      this.component.public.ingestMenstruation,
+      args as never,
+    );
+  }
+
+  /**
+   * Ingest an athlete (user profile) record.
+   *
+   * Upserts by `connectionId` — one athlete record per connection.
+   *
+   * @param ctx - Mutation context from the host app
+   * @param args - Athlete data including connectionId, userId, and profile fields
+   * @returns The athlete document ID
+   */
+  async ingestAthlete(
+    ctx: MutationCtx,
+    args: IngestArgs,
+  ): Promise<string> {
+    return await ctx.runMutation(
+      this.component.public.ingestAthlete,
+      args as never,
+    );
+  }
+}
+
+/**
+ * Common args shape for all ingestion methods.
+ *
+ * Requires `connectionId` and `userId` at minimum — additional fields
+ * come from the transformer output (e.g., `metadata`, `calories_data`, etc.)
+ * and are validated server-side by Convex validators.
+ */
+type IngestArgs = {
+  connectionId: string;
+  userId: string;
+} & Record<string, unknown>;

package/src/client/types.ts

@@ -0,0 +1,18 @@
+import type {
+    GenericActionCtx,
+    GenericMutationCtx,
+    GenericQueryCtx,
+    GenericDataModel,
+} from "convex/server";
+
+export type QueryCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+
+export type MutationCtx = Pick<
+    GenericMutationCtx<GenericDataModel>,
+    "runQuery" | "runMutation"
+>;
+
+export type ActionCtx = Pick<
+    GenericActionCtx<GenericDataModel>,
+    "runQuery" | "runMutation" | "runAction"
+>;