@nativesquare/soma 0.10.2 → 0.12.0

package/src/client/strava.ts

@@ -0,0 +1,108 @@
+import type { SomaComponent } from "./index.js";
+import type { ActionCtx, SomaStravaConfig } from "./types.js";
+
+export class SomaStrava {
+  constructor(
+    private component: SomaComponent,
+    private requireConfig: () => SomaStravaConfig,
+  ) {}
+
+  /**
+   * Generate a Strava OAuth authorization URL.
+   *
+   * The state parameter is stored inside the component automatically,
+   * and the callback handler registered by `registerRoutes` will
+   * complete the flow without further host-app intervention.
+   *
+   * @param ctx - Action context from the host app
+   * @param opts.userId - The host app's user identifier
+   * @param opts.redirectUri - The URL Strava will redirect to after authorization
+   * @param opts.scope - Comma-separated Strava OAuth scopes (default: "read,activity:read_all,profile:read_all")
+   * @returns `{ authUrl, state }`
+   *
+   * @example
+   * ```ts
+   * const { authUrl } = await soma.strava.getAuthUrl(ctx, {
+   *   userId: "user_123",
+   *   redirectUri: "https://your-app.convex.site/api/strava/callback",
+   * });
+   * // Redirect user to authUrl — the callback is handled automatically
+   * ```
+   */
+  async getAuthUrl(
+    ctx: ActionCtx,
+    opts: { userId: string; redirectUri: string; scope?: string },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.strava.public.getStravaAuthUrl, {
+      clientId: config.clientId,
+      redirectUri: opts.redirectUri,
+      scope: opts.scope,
+      userId: opts.userId,
+    });
+  }
+
+  /**
+   * Sync activities from Strava for an already-connected user.
+   *
+   * Automatically refreshes the access token if expired. Fetches the
+   * athlete profile and activities, transforms them, and ingests into Soma.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.after - Only sync activities after this Unix epoch timestamp (for incremental sync)
+   * @returns `{ synced, errors }`
+   *
+   * @example
+   * ```ts
+   * export const syncStrava = action({
+   *   args: { userId: v.string() },
+   *   handler: async (ctx, { userId }) => {
+   *     return await soma.strava.sync(ctx, { userId });
+   *   },
+   * });
+   * ```
+   */
+  async sync(
+    ctx: ActionCtx,
+    args: { userId: string; after?: number },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.strava.public.syncStrava, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Disconnect a user from Strava.
+   *
+   * Revokes the token at Strava (best-effort), deletes stored tokens,
+   * and sets the connection to inactive.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   *
+   * @example
+   * ```ts
+   * export const disconnectStrava = action({
+   *   args: { userId: v.string() },
+   *   handler: async (ctx, { userId }) => {
+   *     await soma.strava.disconnect(ctx, { userId });
+   *   },
+   * });
+   * ```
+   */
+  async disconnect(
+    ctx: ActionCtx,
+    args: { userId: string },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.strava.public.disconnectStrava, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+}

package/src/client/types.ts

@@ -1,18 +1,215 @@
-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"
->;
+import type {
+    GenericActionCtx,
+    GenericMutationCtx,
+    GenericQueryCtx,
+    GenericDataModel,
+} from "convex/server";
+
+// ─── Context Types ──────────────────────────────────────────────────────────
+// Narrowed Convex context types that only expose the runner methods each
+// operation actually needs.
+
+export type QueryCtx = Pick<GenericQueryCtx<GenericDataModel>, "runQuery">;
+
+export type MutationCtx = Pick<
+    GenericMutationCtx<GenericDataModel>,
+    "runQuery" | "runMutation"
+>;
+
+export type ActionCtx = Pick<
+    GenericActionCtx<GenericDataModel>,
+    "runQuery" | "runMutation" | "runAction"
+>;
+
+// ─── Provider Configuration ─────────────────────────────────────────────────
+
+/**
+ * Configuration for the Strava integration.
+ *
+ * If not provided to the Soma constructor, the class will attempt to
+ * read `STRAVA_CLIENT_ID` and `STRAVA_CLIENT_SECRET`
+ * from environment variables automatically.
+ */
+export interface SomaStravaConfig {
+  /** Your Strava application's Client ID. */
+  clientId: string;
+  /** Your Strava application's Client Secret. */
+  clientSecret: string;
+}
+
+/**
+ * Configuration for the Garmin integration.
+ *
+ * If not provided to the Soma constructor, the class will attempt to
+ * read `GARMIN_CLIENT_ID` and `GARMIN_CLIENT_SECRET` from
+ * environment variables automatically.
+ */
+export interface SomaGarminConfig {
+  /** Your Garmin application's Client ID. */
+  clientId: string;
+  /** Your Garmin application's Client Secret. */
+  clientSecret: string;
+}
+
+// ─── Data Query & Ingestion Args ────────────────────────────────────────────
+
+/**
+ * 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.
+ */
+export type IngestArgs = {
+  connectionId: string;
+  userId: string;
+} & Record<string, unknown>;
+
+/**
+ * Base args for time-range filtered queries.
+ *
+ * - `userId` is required for all health data queries.
+ * - `startTime` / `endTime` are optional ISO-8601 bounds on `metadata.start_time`.
+ */
+export type TimeRangeArgs = {
+  userId: string;
+  startTime?: string;
+  endTime?: string;
+};
+
+/**
+ * Args for list (collect-all) queries with optional ordering and limit.
+ */
+export type ListTimeRangeArgs = TimeRangeArgs & {
+  order?: "asc" | "desc";
+  limit?: number;
+};
+
+/**
+ * Args for paginated queries with Convex pagination options.
+ */
+export type PaginateTimeRangeArgs = TimeRangeArgs & {
+  paginationOpts: { numItems: number; cursor: string | null };
+};
+
+// ─── OAuth Callback Events ──────────────────────────────────────────────────
+
+/** Data passed to `onComplete` after Strava OAuth completes. */
+export interface StravaConnectEvent {
+  provider: "STRAVA";
+  userId: string;
+  connectionId: string;
+}
+
+/** Data passed to `oauth.onComplete` after Garmin OAuth completes. */
+export interface GarminConnectEvent {
+  provider: "GARMIN";
+  userId: string;
+  connectionId: string;
+}
+
+// ─── Garmin Webhook Types ───────────────────────────────────────────────────
+
+/** Data passed to webhook `events` handlers and `onEvent` after data ingestion. */
+export interface GarminWebhookEvent {
+  dataType: string;
+  processed: number;
+  errors: Array<{ type: string; id: string; error: string }>;
+  /** Users whose data was affected by this webhook. */
+  affectedUsers: Array<{ userId: string; connectionId: string }>;
+}
+
+/** Webhook endpoint names matching the Garmin API data types. */
+export type GarminWebhookEventName =
+  | "activities" | "activity-details" | "manually-updated-activities" | "move-iq"
+  | "blood-pressures" | "body-compositions" | "dailies" | "epochs"
+  | "health-snapshot" | "sleeps" | "hrv" | "stress" | "pulse-ox"
+  | "respiration" | "skin-temp" | "user-metrics" | "menstrual-cycle-tracking";
+
+/** Handler for a specific webhook event or the catch-all `onEvent`. */
+export type GarminWebhookHandler = (
+  ctx: GenericActionCtx<GenericDataModel>,
+  event: GarminWebhookEvent,
+) => Promise<void>;
+
+// ─── Route Registration Options ─────────────────────────────────────────────
+
+/**
+ * Per-provider options for `registerRoutes`.
+ */
+export interface StravaOAuthOptions {
+  /** HTTP path for the OAuth callback. @default "/api/strava/callback" */
+  path?: string;
+  /** Override STRAVA_CLIENT_ID env var. */
+  clientId?: string;
+  /** Override STRAVA_CLIENT_SECRET env var. */
+  clientSecret?: string;
+  /** URL to redirect the user to after a successful connection. */
+  redirectTo?: string;
+  /** Called after Strava OAuth completes and the connection is established. */
+  onComplete?: (
+    ctx: GenericActionCtx<GenericDataModel>,
+    event: StravaConnectEvent,
+  ) => Promise<void>;
+}
+
+export interface GarminOAuthOptions {
+  /** HTTP path for the OAuth callback. @default "/api/garmin/callback" */
+  path?: string;
+  /** Override GARMIN_CLIENT_ID env var. */
+  clientId?: string;
+  /** Override GARMIN_CLIENT_SECRET env var. */
+  clientSecret?: string;
+  /** URL to redirect the user to after a successful connection. */
+  redirectTo?: string;
+  /** Called after Garmin OAuth completes and the connection is established. */
+  onComplete?: (
+    ctx: GenericActionCtx<GenericDataModel>,
+    event: GarminConnectEvent,
+  ) => Promise<void>;
+}
+
+export interface GarminWebhookOptions {
+  /** Base path prefix for all webhook routes. @default "/api/garmin/webhook" */
+  basePath?: string;
+  /** Called after every webhook payload is processed, regardless of data type. */
+  onEvent?: GarminWebhookHandler;
+  /**
+   * Per-data-type webhook registration.
+   *
+   * **Only data types listed here get an HTTP route registered.**
+   * Unlisted types are ignored — Garmin receives a 404 if it POSTs to them.
+   *
+   * Pass a handler function to run custom logic after ingestion,
+   * or `true` to register the route with default processing only.
+   *
+   * @example
+   * ```ts
+   * events: {
+   *   "activities": async (ctx, event) => { // custom side-effect },
+   *   "sleeps": true,   // register route, default processing only
+   *   "dailies": true,
+   * }
+   * ```
+   */
+  events?: Partial<Record<GarminWebhookEventName, GarminWebhookHandler | true>>;
+}
+
+export interface RegisterRoutesOptions {
+  strava?: {
+    /** OAuth callback configuration. */
+    oauth?: StravaOAuthOptions;
+  };
+  garmin?: {
+    /** OAuth callback configuration. */
+    oauth?: GarminOAuthOptions;
+    /**
+     * Webhook route configuration.
+     *
+     * Routes are **disabled by default**. Only data types listed in `events`
+     * get an HTTP endpoint registered. Omit entirely or set to `false` to
+     * skip all webhook routes.
+     */
+    webhook?: GarminWebhookOptions | false;
+  };
+}

package/src/component/_generated/component.ts

@@ -38,6 +38,30 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           any,
           Name
         >;
+        deleteSchedule: FunctionReference<
+          "action",
+          "internal",
+          {
+            clientId: string;
+            clientSecret: string;
+            plannedWorkoutId: string;
+            userId: string;
+          },
+          any,
+          Name
+        >;
+        deleteWorkout: FunctionReference<
+          "action",
+          "internal",
+          {
+            clientId: string;
+            clientSecret: string;
+            plannedWorkoutId: string;
+            userId: string;
+          },
+          any,
+          Name
+        >;
         disconnectGarmin: FunctionReference<
           "action",
           "internal",
@@ -221,41 +245,28 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           any,
           Name
         >;
-        pushPlannedWorkout: FunctionReference<
+        pushSchedule: FunctionReference<
           "action",
           "internal",
           {
             clientId: string;
             clientSecret: string;
+            date?: string;
             plannedWorkoutId: string;
             userId: string;
-            workoutProvider?: string;
           },
           any,
           Name
         >;
-        syncAllTypes: FunctionReference<
-          "action",
-          "internal",
-          {
-            accessToken: string;
-            connectionId: string;
-            uploadEndTimeInSeconds: number;
-            uploadStartTimeInSeconds: number;
-            userId: string;
-          },
-          any,
-          Name
-        >;
-        syncGarmin: FunctionReference<
+        pushWorkout: FunctionReference<
           "action",
           "internal",
           {
             clientId: string;
             clientSecret: string;
-            endTimeInSeconds?: number;
-            startTimeInSeconds?: number;
+            plannedWorkoutId: string;
             userId: string;
+            workoutProvider?: string;
           },
           any,
           Name