@clipin/convex-wearables 0.0.2 → 0.0.3

package/src/client/types.ts

@@ -0,0 +1,533 @@
+/**
+ * Shared types for @clipin/convex-wearables.
+ *
+ * These types are used by both the component internals and the host app.
+ */
+
+// ---------------------------------------------------------------------------
+// Provider types
+// ---------------------------------------------------------------------------
+
+export type ProviderName =
+  | "garmin"
+  | "suunto"
+  | "polar"
+  | "whoop"
+  | "strava"
+  | "apple"
+  | "samsung"
+  | "google";
+
+export type ConnectionStatus = "active" | "inactive" | "revoked" | "expired" | "error";
+
+export type EventCategory = "workout" | "sleep";
+
+export type SyncJobStatus = "queued" | "running" | "completed" | "failed" | "canceled";
+
+export type BackfillJobStatus = "queued" | "running" | "completed" | "failed" | "canceled";
+
+// ---------------------------------------------------------------------------
+// Provider configuration (passed by app)
+// ---------------------------------------------------------------------------
+
+export interface ProviderCredentials {
+  clientId: string;
+  clientSecret: string;
+  /** Suunto requires an additional subscription key. */
+  subscriptionKey?: string;
+}
+
+export interface WearablesConfig {
+  providers: Partial<Record<ProviderName, ProviderCredentials>>;
+  /**
+   * Optional function reference called when new data is synced.
+   * The host app can use this to trigger downstream processing.
+   */
+  onDataSynced?: unknown; // FunctionReference — typed loosely to avoid coupling
+}
+
+export interface GarminRoutesConfig {
+  /** Route that receives Garmin push notifications. */
+  webhookPath?: string;
+  /** Optional health-check route for the Garmin webhook integration. */
+  healthPath?: string | false;
+  /** Expected Garmin client ID. Defaults to `process.env.GARMIN_CLIENT_ID`. */
+  clientId?: string;
+  /** Garmin client secret. Defaults to `process.env.GARMIN_CLIENT_SECRET`. */
+  clientSecret?: string;
+  /** Route that receives the Garmin OAuth callback. */
+  oauthCallbackPath?: string | false;
+  /** Where to redirect after a successful OAuth callback. */
+  successRedirectUrl?: string;
+  /** Query parameter set on successful OAuth redirect. */
+  successQueryParam?: string;
+}
+
+export interface SdkRoutesConfig {
+  /** Route that receives normalized SDK/mobile health pushes. */
+  syncPath?: string | false;
+  /**
+   * Optional shared bearer token expected on the SDK sync route.
+   * Defaults to `process.env.WEARABLES_SDK_AUTH_TOKEN` when omitted.
+   */
+  authToken?: string;
+}
+
+export interface RegisterRoutesConfig {
+  /**
+   * Garmin webhook routes.
+   * Pass `false` to skip registering Garmin routes.
+   */
+  garmin?: GarminRoutesConfig | false;
+  /**
+   * Normalized SDK push route for Apple Health / Google Health Connect / Samsung Health.
+   * Omitted by default; pass a config object to register it.
+   */
+  sdk?: SdkRoutesConfig | false;
+}
+
+export type SdkProviderName = "apple" | "google" | "samsung";
+
+export interface SdkDeviceMetadata {
+  model?: string;
+  softwareVersion?: string;
+  source?: string;
+  deviceType?: string;
+  originalSourceName?: string;
+}
+
+export interface SdkSourceMetadata {
+  deviceModel?: string;
+  softwareVersion?: string;
+  source?: string;
+  deviceType?: string;
+  originalSourceName?: string;
+}
+
+export interface SdkPushEvent extends SdkSourceMetadata {
+  category: EventCategory;
+  type?: string;
+  sourceName?: string;
+  durationSeconds?: number;
+  startDatetime: number;
+  endDatetime?: number;
+  externalId?: string;
+  heartRateMin?: number;
+  heartRateMax?: number;
+  heartRateAvg?: number;
+  energyBurned?: number;
+  distance?: number;
+  stepsCount?: number;
+  maxSpeed?: number;
+  maxWatts?: number;
+  movingTimeSeconds?: number;
+  totalElevationGain?: number;
+  averageSpeed?: number;
+  averageWatts?: number;
+  elevHigh?: number;
+  elevLow?: number;
+  sleepTotalDurationMinutes?: number;
+  sleepTimeInBedMinutes?: number;
+  sleepEfficiencyScore?: number;
+  sleepDeepMinutes?: number;
+  sleepRemMinutes?: number;
+  sleepLightMinutes?: number;
+  sleepAwakeMinutes?: number;
+  isNap?: boolean;
+  sleepStages?: Array<{
+    stage: string;
+    startTime: number;
+    endTime: number;
+  }>;
+}
+
+export interface SdkPushDataPoint extends SdkSourceMetadata {
+  seriesType: string;
+  recordedAt: number;
+  value: number;
+  externalId?: string;
+}
+
+export interface SdkPushSummary {
+  date: string;
+  category: string;
+  totalSteps?: number;
+  totalCalories?: number;
+  activeCalories?: number;
+  activeMinutes?: number;
+  totalDistance?: number;
+  floorsClimbed?: number;
+  avgHeartRate?: number;
+  maxHeartRate?: number;
+  minHeartRate?: number;
+  sleepDurationMinutes?: number;
+  sleepEfficiency?: number;
+  deepSleepMinutes?: number;
+  remSleepMinutes?: number;
+  lightSleepMinutes?: number;
+  awakeDuringMinutes?: number;
+  timeInBedMinutes?: number;
+  hrvAvg?: number;
+  hrvRmssd?: number;
+  restingHeartRate?: number;
+  recoveryScore?: number;
+  weight?: number;
+  bodyFatPercentage?: number;
+  bodyMassIndex?: number;
+  leanBodyMass?: number;
+  bodyTemperature?: number;
+  avgStressLevel?: number;
+  bodyBattery?: number;
+  spo2Avg?: number;
+}
+
+export interface SdkPushPayload {
+  userId: string;
+  provider: SdkProviderName;
+  providerUserId?: string;
+  providerUsername?: string;
+  syncTimestamp?: number;
+  /**
+   * Compatibility alias for older mobile payloads.
+   * Prefer `sourceMetadata` for new integrations.
+   */
+  device?: SdkDeviceMetadata;
+  sourceMetadata?: SdkSourceMetadata;
+  events?: SdkPushEvent[];
+  dataPoints?: SdkPushDataPoint[];
+  summaries?: SdkPushSummary[];
+  /**
+   * Compatibility alias for older mobile payloads.
+   * Prefer `summaries` for new integrations.
+   */
+  dailySummaries?: SdkPushSummary[];
+}
+
+export type SdkSyncPayload = SdkPushPayload;
+
+// ---------------------------------------------------------------------------
+// Connection types
+// ---------------------------------------------------------------------------
+
+export interface Connection {
+  _id: string;
+  userId: string;
+  provider: ProviderName;
+  providerUserId?: string;
+  providerUsername?: string;
+  status: ConnectionStatus;
+  lastSyncedAt?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Event types
+// ---------------------------------------------------------------------------
+
+export interface WorkoutEvent {
+  _id: string;
+  userId: string;
+  category: "workout";
+  type?: string;
+  sourceName?: string;
+  durationSeconds?: number;
+  startDatetime: number;
+  endDatetime?: number;
+  externalId?: string;
+  // Workout details
+  heartRateMin?: number;
+  heartRateMax?: number;
+  heartRateAvg?: number;
+  energyBurned?: number;
+  distance?: number;
+  stepsCount?: number;
+  maxSpeed?: number;
+  maxWatts?: number;
+  movingTimeSeconds?: number;
+  totalElevationGain?: number;
+  averageSpeed?: number;
+  averageWatts?: number;
+  elevHigh?: number;
+  elevLow?: number;
+}
+
+export interface SleepStage {
+  stage: string;
+  startTime: number;
+  endTime: number;
+}
+
+export interface SleepEvent {
+  _id: string;
+  userId: string;
+  category: "sleep";
+  type?: string;
+  sourceName?: string;
+  durationSeconds?: number;
+  startDatetime: number;
+  endDatetime?: number;
+  externalId?: string;
+  // Sleep details
+  sleepTotalDurationMinutes?: number;
+  sleepTimeInBedMinutes?: number;
+  sleepEfficiencyScore?: number;
+  sleepDeepMinutes?: number;
+  sleepRemMinutes?: number;
+  sleepLightMinutes?: number;
+  sleepAwakeMinutes?: number;
+  isNap?: boolean;
+  sleepStages?: SleepStage[];
+}
+
+export type HealthEvent = WorkoutEvent | SleepEvent;
+
+// ---------------------------------------------------------------------------
+// Data point types
+// ---------------------------------------------------------------------------
+
+export interface DataPoint {
+  timestamp: number;
+  value: number;
+}
+
+export interface TimeSeriesPage {
+  points: DataPoint[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Events page
+// ---------------------------------------------------------------------------
+
+export interface EventsPage {
+  events: HealthEvent[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Summary types
+// ---------------------------------------------------------------------------
+
+export interface DailySummary {
+  _id: string;
+  userId: string;
+  date: string;
+  category: string;
+  // Activity
+  totalSteps?: number;
+  totalCalories?: number;
+  activeCalories?: number;
+  activeMinutes?: number;
+  totalDistance?: number;
+  floorsClimbed?: number;
+  avgHeartRate?: number;
+  maxHeartRate?: number;
+  minHeartRate?: number;
+  // Sleep
+  sleepDurationMinutes?: number;
+  sleepEfficiency?: number;
+  deepSleepMinutes?: number;
+  remSleepMinutes?: number;
+  lightSleepMinutes?: number;
+  awakeDuringMinutes?: number;
+  timeInBedMinutes?: number;
+  // Recovery
+  hrvAvg?: number;
+  hrvRmssd?: number;
+  restingHeartRate?: number;
+  recoveryScore?: number;
+  // Body
+  weight?: number;
+  bodyFatPercentage?: number;
+  bodyMassIndex?: number;
+  leanBodyMass?: number;
+  bodyTemperature?: number;
+  // Other
+  avgStressLevel?: number;
+  bodyBattery?: number;
+  spo2Avg?: number;
+}
+
+export interface AggregateStats {
+  sum: number;
+  count: number;
+  avg: number;
+  min: number | null;
+  max: number | null;
+}
+
+// ---------------------------------------------------------------------------
+// Sync status
+// ---------------------------------------------------------------------------
+
+export interface SyncJob {
+  _id: string;
+  connectionId: string;
+  userId: string;
+  provider: ProviderName;
+  status: SyncJobStatus;
+  mode?: "manual" | "cron" | "webhook";
+  triggerSource?: string;
+  startedAt: number;
+  completedAt?: number;
+  error?: string;
+  recordsProcessed?: number;
+  workflowId?: string;
+  windowStart?: number;
+  windowEnd?: number;
+  attempt?: number;
+  lastHeartbeatAt?: number;
+  cursor?: string;
+  currentPhase?: "events" | "dataPoints" | "summaries";
+}
+
+export interface SyncStatus {
+  provider: ProviderName;
+  connectionStatus: ConnectionStatus;
+  lastSyncedAt?: number;
+  syncJobStatus: SyncJobStatus | null;
+  syncJobError: string | null;
+}
+
+export interface BackfillJob {
+  _id: string;
+  connectionId: string;
+  userId: string;
+  provider: ProviderName;
+  dataType: string;
+  status: BackfillJobStatus;
+  startedAt: number;
+  completedAt?: number;
+  error?: string;
+  workflowId?: string;
+  windowStart?: number;
+  windowEnd?: number;
+  currentDataType?: string;
+  currentAttempt?: number;
+  currentEventId?: string;
+  completedDataTypes?: string[];
+  lastHeartbeatAt?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Series type definitions — all 48 pre-defined metric types
+// ---------------------------------------------------------------------------
+
+export const SERIES_TYPES = {
+  // Heart & Cardiovascular
+  heart_rate: { id: 1, unit: "bpm" },
+  resting_heart_rate: { id: 2, unit: "bpm" },
+  heart_rate_variability_sdnn: { id: 3, unit: "ms" },
+  heart_rate_recovery_one_minute: { id: 4, unit: "bpm" },
+  walking_heart_rate_average: { id: 5, unit: "bpm" },
+  recovery_score: { id: 6, unit: "score" },
+  heart_rate_variability_rmssd: { id: 7, unit: "ms" },
+
+  // Blood & Respiratory
+  oxygen_saturation: { id: 20, unit: "percent" },
+  blood_glucose: { id: 21, unit: "mg_dl" },
+  blood_pressure_systolic: { id: 22, unit: "mmHg" },
+  blood_pressure_diastolic: { id: 23, unit: "mmHg" },
+  respiratory_rate: { id: 24, unit: "brpm" },
+  sleeping_breathing_disturbances: { id: 25, unit: "count" },
+  blood_alcohol_content: { id: 26, unit: "mg_dl" },
+  peripheral_perfusion_index: { id: 27, unit: "score" },
+  forced_vital_capacity: { id: 28, unit: "liters" },
+  forced_expiratory_volume_1: { id: 29, unit: "liters" },
+  peak_expiratory_flow_rate: { id: 30, unit: "liters" },
+
+  // Body Composition
+  height: { id: 40, unit: "cm" },
+  weight: { id: 41, unit: "kg" },
+  body_fat_percentage: { id: 42, unit: "percent" },
+  body_mass_index: { id: 43, unit: "kg_m2" },
+  lean_body_mass: { id: 44, unit: "kg" },
+  body_temperature: { id: 45, unit: "celsius" },
+  skin_temperature: { id: 46, unit: "celsius" },
+  waist_circumference: { id: 47, unit: "cm" },
+  body_fat_mass: { id: 48, unit: "kg" },
+  skeletal_muscle_mass: { id: 49, unit: "kg" },
+
+  // Fitness
+  vo2_max: { id: 60, unit: "ml_kg_min" },
+  six_minute_walk_test_distance: { id: 61, unit: "meters" },
+
+  // Activity — Basic
+  steps: { id: 80, unit: "count" },
+  energy: { id: 81, unit: "kcal" },
+  basal_energy: { id: 82, unit: "kcal" },
+  total_calories: { id: 88, unit: "kcal" },
+  active_calories: { id: 89, unit: "kcal" },
+  stand_time: { id: 83, unit: "minutes" },
+  exercise_time: { id: 84, unit: "minutes" },
+  physical_effort: { id: 85, unit: "score" },
+  flights_climbed: { id: 86, unit: "count" },
+  floors_climbed: { id: 90, unit: "count" },
+  average_met: { id: 87, unit: "met" },
+
+  // Activity — Distance
+  distance: { id: 99, unit: "meters" },
+  distance_walking_running: { id: 100, unit: "meters" },
+  distance_cycling: { id: 101, unit: "meters" },
+  distance_swimming: { id: 102, unit: "meters" },
+  distance_downhill_snow_sports: { id: 103, unit: "meters" },
+  distance_other: { id: 104, unit: "meters" },
+  elevation_gain: { id: 105, unit: "meters" },
+
+  // Activity — Walking
+  walking_step_length: { id: 120, unit: "cm" },
+  walking_speed: { id: 121, unit: "m_per_s" },
+  walking_double_support_percentage: { id: 122, unit: "percent" },
+  walking_asymmetry_percentage: { id: 123, unit: "percent" },
+  walking_steadiness: { id: 124, unit: "percent" },
+  stair_descent_speed: { id: 125, unit: "m_per_s" },
+  stair_ascent_speed: { id: 126, unit: "m_per_s" },
+
+  // Activity — Running
+  running_power: { id: 140, unit: "watts" },
+  running_speed: { id: 141, unit: "m_per_s" },
+  running_vertical_oscillation: { id: 142, unit: "cm" },
+  running_ground_contact_time: { id: 143, unit: "ms" },
+  running_stride_length: { id: 144, unit: "cm" },
+
+  // Activity — Swimming
+  swimming_stroke_count: { id: 160, unit: "count" },
+  underwater_depth: { id: 161, unit: "meters" },
+
+  // Activity — Generic
+  cadence: { id: 180, unit: "rpm" },
+  power: { id: 181, unit: "watts" },
+  speed: { id: 182, unit: "m_per_s" },
+  workout_effort_score: { id: 183, unit: "score" },
+  estimated_workout_effort_score: { id: 184, unit: "score" },
+
+  // Environmental
+  environmental_audio_exposure: { id: 200, unit: "dB" },
+  headphone_audio_exposure: { id: 201, unit: "dB" },
+  environmental_sound_reduction: { id: 202, unit: "dB" },
+  time_in_daylight: { id: 203, unit: "minutes" },
+  water_temperature: { id: 204, unit: "celsius" },
+  uv_exposure: { id: 205, unit: "count" },
+  inhaler_usage: { id: 206, unit: "count" },
+  weather_temperature: { id: 207, unit: "celsius" },
+  weather_humidity: { id: 208, unit: "percent" },
+
+  // Garmin-Specific
+  garmin_stress_level: { id: 220, unit: "score" },
+  garmin_skin_temperature: { id: 221, unit: "celsius" },
+  garmin_fitness_age: { id: 222, unit: "years" },
+  garmin_body_battery: { id: 223, unit: "percent" },
+
+  // Other
+  electrodermal_activity: { id: 500, unit: "count" },
+  push_count: { id: 501, unit: "count" },
+  atrial_fibrillation_burden: { id: 502, unit: "count" },
+  insulin_delivery: { id: 503, unit: "count" },
+  number_of_times_fallen: { id: 504, unit: "count" },
+  number_of_alcoholic_beverages: { id: 505, unit: "count" },
+  nike_fuel: { id: 506, unit: "count" },
+  hydration: { id: 507, unit: "mL" },
+} as const;
+
+export type SeriesType = keyof typeof SERIES_TYPES;

package/src/component/_generated/_ignore.ts

@@ -0,0 +1,2 @@
+// This file exists so that the _generated directory is tracked by git.
+// The actual generated files are created by `npx convex dev` or `npx convex codegen`.

package/src/component/_generated/api.ts

@@ -0,0 +1,16 @@
+/* eslint-disable */
+/**
+ * Generated API.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { AnyApi, AnyComponents } from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+export const api: AnyApi = anyApi;
+export const internal: AnyApi = anyApi;
+export const components: AnyComponents = componentsGeneric();

package/src/component/_generated/component.ts

@@ -0,0 +1,74 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { ApiFromModules, FilterApi, FunctionReference } from "convex/server";
+import type { GenericId as ConvexId } from "convex/values";
+
+type Modules = {
+  backfillJobs: typeof import("../backfillJobs.js");
+  connections: typeof import("../connections.js");
+  dataPoints: typeof import("../dataPoints.js");
+  dataSources: typeof import("../dataSources.js");
+  events: typeof import("../events.js");
+  garminBackfill: typeof import("../garminBackfill.js");
+  garminWebhooks: typeof import("../garminWebhooks.js");
+  lifecycle: typeof import("../lifecycle.js");
+  menstrualCycles: typeof import("../menstrualCycles.js");
+  oauthActions: typeof import("../oauthActions.js");
+  sdkPush: typeof import("../sdkPush.js");
+  summaries: typeof import("../summaries.js");
+  syncJobs: typeof import("../syncJobs.js");
+  syncWorkflow: typeof import("../syncWorkflow.js");
+};
+
+type PublicApi = FilterApi<
+  ApiFromModules<Modules>,
+  FunctionReference<any, "public", any, any>
+>;
+
+type ConvertComponentBoundary<T> =
+  T extends ConvexId<string>
+    ? string
+    : T extends readonly (infer Item)[]
+      ? Array<ConvertComponentBoundary<Item>>
+      : T extends object
+        ? { [Key in keyof T]: ConvertComponentBoundary<T[Key]> }
+        : T;
+
+type ConvertComponentArgs<Args extends Record<string, any>> = {
+  [Key in keyof Args]: ConvertComponentBoundary<Args[Key]>;
+};
+
+type ToComponentApi<API, Name extends string | undefined> =
+  API extends FunctionReference<infer Type, any, infer Args, infer ReturnType>
+    ? FunctionReference<
+        Type,
+        "internal",
+        ConvertComponentArgs<Args>,
+        ConvertComponentBoundary<ReturnType>,
+        Name
+      >
+    : API extends object
+      ? { [Key in keyof API]: ToComponentApi<API[Key], Name> }
+      : never;
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  ToComponentApi<PublicApi, Name>;

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,40 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ */
+export type Id<TableName extends TableNames> = GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;