@nativesquare/soma 0.12.0 → 0.13.0

package/src/client/index.ts

@@ -8,11 +8,11 @@ import type {
   ListTimeRangeArgs,
   PaginateTimeRangeArgs,
   RegisterRoutesOptions,
-  GarminWebhookEventName,
-  GarminWebhookEvent,
 } from "./types.js";
 export type {
   ActionCtx,
+  SomaError,
+  SomaResult,
   SomaStravaConfig,
   SomaGarminConfig,
   IngestArgs,
@@ -22,6 +22,8 @@ export type {
   StravaOAuthOptions,
   StravaConnectEvent,
   GarminConnectEvent,
+  GarminWebhookActionArgs,
+  GarminWebhookActionResult,
   GarminWebhookEvent,
   GarminOAuthOptions,
   GarminWebhookEventName,
@@ -29,26 +31,17 @@ export type {
   GarminWebhookOptions,
   RegisterRoutesOptions,
 } from "./types.js";
-import {
-  httpActionGeneric,
-  type FunctionReference,
-  type HttpRouter,
-} from "convex/server";
+import type { HttpRouter } from "convex/server";
 import { SomaGarmin } from "./garmin.js";
 import { SomaStrava } from "./strava.js";
 
 export { SomaGarmin } from "./garmin.js";
 export { SomaStrava } from "./strava.js";
+export { STRAVA_CALLBACK_PATH } from "./strava.js";
+export { GARMIN_OAUTH_CALLBACK_PATH, GARMIN_WEBHOOK_BASE_PATH } from "./garmin.js";
 
 export type SomaComponent = ComponentApi;
 
-// ─── Default OAuth Callback Paths ────────────────────────────────────────────
-// Used by `registerRoutes` as defaults. Override per-provider in the opts.
-
-export const STRAVA_CALLBACK_PATH = "/api/strava/callback";
-export const GARMIN_OAUTH_CALLBACK_PATH = "/api/garmin/callback";
-export const GARMIN_WEBHOOK_BASE_PATH = "/api/garmin/webhook";
-
 /**
  * Client class for the @nativesquare/soma Convex component.
  *
@@ -851,7 +844,7 @@ export class Soma {
  *       },
  *       // Optional catch-all, runs for every registered event
  *       onEvent: async (ctx, event) => {
- *         console.log(`Garmin ${event.dataType}: ${event.processed} processed`);
+ *         console.log(`Garmin ${event.dataType}: ${event.items.length} items`);
  *       },
  *     },
  *   },
@@ -866,272 +859,10 @@ export function registerRoutes(
   const registerAll = opts === undefined;
 
   if (registerAll || opts?.strava) {
-    const stravaOpts = opts?.strava ?? {};
-    const oauth = stravaOpts.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 =
-          oauth.clientId ?? process.env.STRAVA_CLIENT_ID;
-        const clientSecret =
-          oauth.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,
-        });
-      }),
-    });
+    SomaStrava.registerRoutes(http, component, opts?.strava);
   }
 
   if (registerAll || opts?.garmin) {
-    const garminOpts = opts?.garmin ?? {};
-    const oauth = garminOpts.oauth ?? {};
-    const path = oauth.path ?? GARMIN_OAUTH_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 Garmin auth URL.",
-            { status: 400 },
-          );
-        }
-
-        const clientId =
-          oauth.clientId ?? process.env.GARMIN_CLIENT_ID;
-        const clientSecret =
-          oauth.clientSecret ?? process.env.GARMIN_CLIENT_SECRET;
-
-        if (!clientId || !clientSecret) {
-          return new Response(
-            "Garmin credentials not configured. Set GARMIN_CLIENT_ID and " +
-            "GARMIN_CLIENT_SECRET environment variables, or pass them to registerRoutes.",
-            { status: 500 },
-          );
-        }
-
-        let result: {
-          connectionId: string;
-          userId: string;
-        };
-        try {
-          result = await ctx.runAction(component.garmin.public.completeGarminOAuth, {
-            code,
-            state,
-            clientId,
-            clientSecret,
-          }) as typeof result;
-        } catch (error) {
-          const message =
-            error instanceof Error ? error.message : "Unknown error";
-          return new Response(`Garmin OAuth callback failed: ${message}`, {
-            status: 500,
-          });
-        }
-
-        if (oauth.onComplete) {
-          try {
-            await oauth.onComplete(ctx, {
-              provider: "GARMIN",
-              userId: result.userId,
-              connectionId: result.connectionId,
-            });
-          } catch (callbackError) {
-            console.error(
-              "[soma] garmin oauth.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 Garmin!", {
-          status: 200,
-        });
-      }),
-    });
-
-    // ── Garmin Webhook Routes ──────────────────────────────────
-    const webhookCfg = typeof garminOpts.webhook === "object" ? garminOpts.webhook : undefined;
-    if (webhookCfg?.events) {
-      const webhookBase = webhookCfg.basePath ?? GARMIN_WEBHOOK_BASE_PATH;
-
-      const webhookRoutes: Array<{
-        suffix: string;
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        action: FunctionReference<"action", "internal", { payload: any }>;
-      }> = [
-          // ACTIVITY category
-          { suffix: "/activities", action: component.garmin.webhooks.handleGarminWebhookActivities },
-          { suffix: "/activity-details", action: component.garmin.webhooks.handleGarminWebhookActivityDetails },
-          { suffix: "/manually-updated-activities", action: component.garmin.webhooks.handleGarminWebhookManuallyUpdatedActivities },
-          { suffix: "/move-iq", action: component.garmin.webhooks.handleGarminWebhookMoveIQ },
-          // HEALTH category
-          { suffix: "/blood-pressures", action: component.garmin.webhooks.handleGarminWebhookBloodPressures },
-          { suffix: "/body-compositions", action: component.garmin.webhooks.handleGarminWebhookBodyCompositions },
-          { suffix: "/dailies", action: component.garmin.webhooks.handleGarminWebhookDailies },
-          { suffix: "/epochs", action: component.garmin.webhooks.handleGarminWebhookEpochs },
-          { suffix: "/health-snapshot", action: component.garmin.webhooks.handleGarminWebhookHealthSnapshot },
-          { suffix: "/sleeps", action: component.garmin.webhooks.handleGarminWebhookSleeps },
-          { suffix: "/hrv", action: component.garmin.webhooks.handleGarminWebhookHRVSummary },
-          { suffix: "/stress", action: component.garmin.webhooks.handleGarminWebhookStress },
-          { suffix: "/pulse-ox", action: component.garmin.webhooks.handleGarminWebhookPulseOx },
-          { suffix: "/respiration", action: component.garmin.webhooks.handleGarminWebhookRespiration },
-          { suffix: "/skin-temp", action: component.garmin.webhooks.handleGarminWebhookSkinTemp },
-          { suffix: "/user-metrics", action: component.garmin.webhooks.handleGarminWebhookUserMetrics },
-          // WOMEN_HEALTH category
-          { suffix: "/menstrual-cycle-tracking", action: component.garmin.webhooks.handleGarminWebhookMenstrualCycleTracking },
-        ];
-
-      for (const route of webhookRoutes) {
-        const dataType = route.suffix.slice(1) as GarminWebhookEventName;
-
-        // Only register routes the host app explicitly opted into
-        if (!webhookCfg.events?.[dataType]) continue;
-
-        http.route({
-          path: `${webhookBase}${route.suffix}`,
-          method: "POST",
-          handler: httpActionGeneric(async (ctx, request) => {
-            let payload: unknown;
-            try {
-              payload = await request.json();
-            } catch {
-              return new Response("Invalid JSON body", { status: 400 });
-            }
-
-            let result: { processed: number; errors: Array<{ type: string; id: string; error: string }>; affectedUsers: Array<{ userId: string; connectionId: string }> } | undefined;
-            try {
-              result = await ctx.runAction(route.action, { payload }) as typeof result;
-            } catch (error) {
-              // Log but return 200 to prevent Garmin from retrying
-              console.error(
-                `Garmin webhook error (${route.suffix}):`,
-                error instanceof Error ? error.message : error,
-              );
-            }
-
-            if (result) {
-              const event: GarminWebhookEvent = {
-                dataType,
-                processed: result.processed,
-                errors: result.errors,
-                affectedUsers: result.affectedUsers,
-              };
-
-              const specificHandler = webhookCfg.events?.[dataType];
-              if (typeof specificHandler === "function") {
-                try {
-                  await specificHandler(ctx, event);
-                } catch (callbackError) {
-                  console.error(
-                    `[soma] garmin webhook events["${dataType}"] callback error:`,
-                    callbackError instanceof Error ? callbackError.message : callbackError,
-                  );
-                }
-              }
-
-              if (webhookCfg.onEvent) {
-                try {
-                  await webhookCfg.onEvent(ctx, event);
-                } catch (callbackError) {
-                  console.error(
-                    `[soma] garmin webhook onEvent callback error:`,
-                    callbackError instanceof Error ? callbackError.message : callbackError,
-                  );
-                }
-              }
-            }
-
-            return new Response("OK", { status: 200 });
-          }),
-        });
-      }
-    }
+    SomaGarmin.registerRoutes(http, component, opts?.garmin);
   }
 }

package/src/client/strava.ts

@@ -1,108 +1,199 @@
-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,
-    });
-  }
-}
+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,
+        });
+      }),
+    });
+  }
+}