@nativesquare/soma 0.11.0 → 0.13.0

package/src/client/strava.ts

@@ -0,0 +1,199 @@
+import type { SomaComponent } from "./index.js";
+import type { ActionCtx, SomaStravaConfig, RegisterRoutesOptions } from "./types.js";
+import { httpActionGeneric, type HttpRouter } from "convex/server";
+
+export const STRAVA_CALLBACK_PATH = "/api/strava/callback";
+
+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,
+    });
+  }
+
+  static registerRoutes(
+    http: HttpRouter,
+    component: SomaComponent,
+    opts?: RegisterRoutesOptions["strava"],
+  ) {
+    const oauth = opts?.oauth ?? {};
+    const path = oauth.path ?? STRAVA_CALLBACK_PATH;
+
+    http.route({
+      path,
+      method: "GET",
+      handler: httpActionGeneric(async (ctx, request) => {
+        const url = new URL(request.url);
+        const code = url.searchParams.get("code");
+        const state = url.searchParams.get("state");
+
+        if (!code) {
+          return new Response("Missing authorization code", { status: 400 });
+        }
+        if (!state) {
+          return new Response(
+            "Missing state parameter. Ensure the state was included " +
+            "when building the Strava auth URL via getStravaAuthUrl.",
+            { status: 400 },
+          );
+        }
+
+        const clientId =
+          opts?.clientId ?? process.env.STRAVA_CLIENT_ID;
+        const clientSecret =
+          opts?.clientSecret ?? process.env.STRAVA_CLIENT_SECRET;
+
+        if (!clientId || !clientSecret) {
+          return new Response(
+            "Strava credentials not configured. Set STRAVA_CLIENT_ID and " +
+            "STRAVA_CLIENT_SECRET environment variables, or pass them to registerRoutes.",
+            { status: 500 },
+          );
+        }
+
+        let result: {
+          connectionId: string;
+          userId: string;
+        };
+        try {
+          result = await ctx.runAction(component.strava.public.completeStravaOAuth, {
+            code,
+            state,
+            clientId,
+            clientSecret,
+          });
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : "Unknown error";
+          return new Response(`Strava OAuth callback failed: ${message}`, {
+            status: 500,
+          });
+        }
+
+        if (oauth.onComplete) {
+          try {
+            await oauth.onComplete(ctx, {
+              provider: "STRAVA",
+              userId: result.userId,
+              connectionId: result.connectionId,
+            });
+          } catch (callbackError) {
+            console.error(
+              "[soma] strava onComplete callback error:",
+              callbackError instanceof Error ? callbackError.message : callbackError,
+            );
+          }
+        }
+
+        if (oauth.redirectTo) {
+          return new Response(null, {
+            status: 302,
+            headers: { Location: oauth.redirectTo },
+          });
+        }
+
+        return new Response("Successfully connected to Strava!", {
+          status: 200,
+        });
+      }),
+    });
+  }
+}

package/src/client/types.ts

@@ -5,6 +5,10 @@ import type {
     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<
@@ -16,3 +20,284 @@ 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;
+}
+
+// ─── Shared Error & Result Types ───────────────────────────────────────────
+
+/**
+ * A structured error from a Soma operation.
+ *
+ * Operational errors (API failures, transform errors, ingestion failures)
+ * are returned in the result — not thrown. Only configuration errors
+ * (missing connection, nonexistent document) are thrown as exceptions.
+ */
+export interface SomaError {
+  /** Category of the failed item (e.g. `"activity"`, `"pushWorkout"`, `"ingest"`). */
+  type: string;
+  /** Identifier of the failed item, or `"fetch"` for API-level failures. */
+  id: string;
+  /** Human-readable error description. */
+  message: string;
+}
+
+/**
+ * Standard result wrapper for all Soma data operations.
+ *
+ * - `data` contains the operation's success payload.
+ * - `errors` contains any operational failures that occurred.
+ *
+ * For **batch operations** (pull, sync), partial success is possible:
+ * `data` contains the counts of successfully processed items, while
+ * `errors` lists the individual failures.
+ *
+ * For **atomic operations** (push, delete), `data` is `null` when the
+ * operation fails, with a single entry in `errors` describing the cause.
+ */
+export type SomaResult<T> = {
+  data: T;
+  errors: SomaError[];
+};
+
+// ─── 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 ───────────────────────────────────────────────────
+
+/** Args accepted by all Garmin webhook handler actions inside the component. */
+export type GarminWebhookActionArgs = {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  payload: any;
+  autoIngest?: boolean;
+};
+
+/** Result returned by all Garmin webhook handler actions inside the component. */
+export interface GarminWebhookActionResult {
+  errors: SomaError[];
+  items: GarminWebhookItem[];
+}
+
+/** A single transformed item with its user/connection mapping. */
+export interface GarminWebhookItem {
+  /** The Soma connection ID that this data belongs to. */
+  connectionId: string;
+  /** The host app's user ID. */
+  userId: string;
+  /** The transformed data in Soma's normalized format. */
+  data: Record<string, unknown>;
+}
+
+/**
+ * Data passed to webhook `events` handlers and `onEvent` after processing.
+ *
+ * The host app receives the full set of transformed items plus the raw Garmin
+ * payload, regardless of the `autoIngest` setting.
+ */
+export interface GarminWebhookEvent {
+  /** The Garmin data type that triggered this webhook (e.g. `"activities"`, `"sleeps"`). */
+  dataType: string;
+  /** Errors encountered during connection resolution, transformation, or ingestion. */
+  errors: SomaError[];
+  /** The raw JSON payload received from Garmin, before any transformation. */
+  rawPayload: unknown;
+  /**
+   * Transformed items in Soma's normalized format.
+   *
+   * Always contains the full set of successfully transformed items, regardless
+   * of the `autoIngest` setting. When `autoIngest` is `true`, these are the
+   * same items that were written to the database. When `autoIngest` is `false`,
+   * the host app can use them for custom ingestion or processing.
+   *
+   * Empty for ping-mode webhooks (which contain no data).
+   */
+  items: GarminWebhookItem[];
+}
+
+/** 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;
+  /** 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;
+  /** 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;
+  /**
+   * Whether to automatically ingest (upsert) transformed data into the Soma
+   * database when a webhook payload is received.
+   *
+   * When `true` (default), incoming data is validated, transformed, and written
+   * to the database automatically. When `false`, the webhook still receives and
+   * validates the payload, but skips the database write — useful when you want
+   * to handle ingestion yourself via the `onEvent` / per-type callbacks.
+   *
+   * @default true
+   */
+  autoIngest?: boolean;
+  /** 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?: {
+    /** Override STRAVA_CLIENT_ID env var. */
+    clientId?: string;
+    /** Override STRAVA_CLIENT_SECRET env var. */
+    clientSecret?: string;
+    /** OAuth callback configuration. */
+    oauth?: StravaOAuthOptions;
+  };
+  garmin?: {
+    /** Override GARMIN_CLIENT_ID env var. */
+    clientId?: string;
+    /** Override GARMIN_CLIENT_SECRET env var. */
+    clientSecret?: string;
+    /** 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

@@ -245,19 +245,6 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           any,
           Name
         >;
-        pushPlannedWorkout: FunctionReference<
-          "action",
-          "internal",
-          {
-            clientId: string;
-            clientSecret: string;
-            plannedWorkoutId: string;
-            userId: string;
-            workoutProvider?: string;
-          },
-          any,
-          Name
-        >;
         pushSchedule: FunctionReference<
           "action",
           "internal",
@@ -289,119 +276,119 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         handleGarminWebhookActivities: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookActivityDetails: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookBloodPressures: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookBodyCompositions: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookDailies: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookEpochs: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookHealthSnapshot: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookHRVSummary: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookManuallyUpdatedActivities: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookMenstrualCycleTracking: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookMoveIQ: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookPulseOx: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookRespiration: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookSkinTemp: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookSleeps: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookStress: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
         handleGarminWebhookUserMetrics: FunctionReference<
           "action",
           "internal",
-          { payload: any },
+          { autoIngest?: boolean; payload: any },
           any,
           Name
         >;
@@ -1880,8 +1867,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             userId: string;
           },
           {
-            errors: Array<{ error: string; id: string; type: string }>;
-            synced: { activities: number; athletes: number };
+            data: { synced: { activities: number; athletes: number } };
+            errors: Array<{ id: string; message: string; type: string }>;
           },
           Name
         >;