@nativesquare/soma 0.11.0 → 0.13.0

package/dist/client/index.js

@@ -1,9 +1,9 @@
-import { httpActionGeneric, } from "convex/server";
-// ─── 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";
+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";
 /**
  * Client class for the @nativesquare/soma Convex component.
  *
@@ -11,7 +11,7 @@ export const GARMIN_WEBHOOK_BASE_PATH = "/api/garmin/webhook";
  * 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" })`
+ * `ctx.runQuery(components.soma.public.listActivities, { userId: "user_123" })`
  *
  * @example
  * ```ts
@@ -20,35 +20,38 @@ export const GARMIN_WEBHOOK_BASE_PATH = "/api/garmin/webhook";
  * import { components } from "./_generated/api";
  *
  * // Zero config if env vars are set in Convex dashboard:
- * //   STRAVA_CLIENT_ID, STRAVA_CLIENT_SECRET, STRAVA_BASE_URL (optional)
+ * //   STRAVA_CLIENT_ID, STRAVA_CLIENT_SECRET
+ * //   GARMIN_CLIENT_ID, GARMIN_CLIENT_SECRET
  * const soma = new Soma(components.soma);
  *
- * // Or with explicit Strava config:
+ * // Or with explicit config:
  * // const soma = new Soma(components.soma, {
  * //   strava: { clientId: "...", clientSecret: "..." },
+ * //   garmin: { clientId: "...", clientSecret: "..." },
  * // });
  *
- * // Connect a user to a provider:
- * const connectionId = await soma.connect(ctx, {
- *   userId: "user_123",
- *   provider: "GARMIN",
- * });
- *
  * // Start Strava OAuth (redirects user, callback handled by registerRoutes):
- * const { authUrl } = await soma.getStravaAuthUrl(ctx, {
+ * const { authUrl } = await soma.strava.getAuthUrl(ctx, {
  *   userId: "user_123",
  *   redirectUri: "https://your-app.convex.site/api/strava/callback",
  * });
+ *
+ * // Pull all Garmin data:
+ * await soma.garmin.pullAll(ctx, { userId: "user_123" });
  * ```
  */
 export class Soma {
     component;
     stravaConfig;
     garminConfig;
+    garmin;
+    strava;
     constructor(component, options) {
         this.component = component;
         this.stravaConfig = options?.strava ?? this.readStravaEnv();
         this.garminConfig = options?.garmin ?? this.readGarminEnv();
+        this.garmin = new SomaGarmin(this.component, () => this.requireGarminConfig());
+        this.strava = new SomaStrava(this.component, () => this.requireStravaConfig());
     }
     /**
      * Read Strava config from environment variables.
@@ -97,57 +100,6 @@ export class Soma {
         }
         return this.garminConfig;
     }
-    // ─── 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, args) {
-        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, args) {
-        return await ctx.runMutation(this.component.public.disconnect, args);
-    }
     // ─── Connection Queries ─────────────────────────────────────────────────────
     /**
      * Get a connection by its document ID.
@@ -571,253 +523,6 @@ export class Soma {
     async getPlannedWorkout(ctx, args) {
         return await ctx.runQuery(this.component.public.getPlannedWorkout, args);
     }
-    // ─── Strava Integration ──────────────────────────────────────────────────────
-    // High-level methods that handle OAuth, token storage, and data syncing
-    // for Strava. Requires Strava credentials to be configured either via
-    // environment variables or the constructor.
-    /**
-     * 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.getStravaAuthUrl(ctx, {
-     *   userId: "user_123",
-     *   redirectUri: "https://your-app.convex.site/api/strava/callback",
-     * });
-     * // Redirect user to authUrl — the callback is handled automatically
-     * ```
-     */
-    async getStravaAuthUrl(ctx, opts) {
-        const config = this.requireStravaConfig();
-        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.syncStrava(ctx, { userId });
-     *   },
-     * });
-     * ```
-     */
-    async syncStrava(ctx, args) {
-        const config = this.requireStravaConfig();
-        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.disconnectStrava(ctx, { userId });
-     *   },
-     * });
-     * ```
-     */
-    async disconnectStrava(ctx, args) {
-        const config = this.requireStravaConfig();
-        return await ctx.runAction(this.component.strava.public.disconnectStrava, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    // ─── Garmin ──────────────────────────────────────────────────────
-    async getGarminAuthUrl(ctx, opts) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.getGarminAuthUrl, {
-            clientId: config.clientId,
-            redirectUri: opts.redirectUri,
-            userId: opts.userId,
-        });
-    }
-    async disconnectGarmin(ctx, args) {
-        return await ctx.runAction(this.component.garmin.public.disconnectGarmin, args);
-    }
-    async pullGarminActivities(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullActivities, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminDailies(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullDailies, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminSleep(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullSleep, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminBody(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullBody, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminMenstruation(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullMenstruation, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminBloodPressures(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullBloodPressures, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminSkinTemperature(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullSkinTemperature, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminUserMetrics(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullUserMetrics, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminHRV(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullHRV, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminStressDetails(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullStressDetails, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminPulseOx(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullPulseOx, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminRespiration(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullRespiration, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pullGarminAll(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pullAll, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pushPlannedWorkoutToGarmin(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pushPlannedWorkout, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pushWorkoutToGarmin(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pushWorkout, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async pushScheduleToGarmin(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.pushSchedule, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async deleteWorkoutFromGarmin(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.deleteWorkout, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
-    async deleteScheduleFromGarmin(ctx, args) {
-        const config = this.requireGarminConfig();
-        return await ctx.runAction(this.component.garmin.public.deleteSchedule, {
-            ...args,
-            clientId: config.clientId,
-            clientSecret: config.clientSecret,
-        });
-    }
 }
 /**
  * Register OAuth callback HTTP routes for Soma providers.
@@ -876,14 +581,18 @@ export class Soma {
  *       },
  *     },
  *     webhook: {
- *       onEvent: async (ctx, event) => {
- *         // Catch-all: runs for every webhook
- *         console.log(`Garmin ${event.dataType}: ${event.processed} processed`);
- *       },
+ *       // Only listed data types get an HTTP route registered.
+ *       // Pass a handler for custom logic, or `true` for default processing.
  *       events: {
  *         "activities": async (ctx, event) => {
- *           // Runs only for activity webhooks
+ *           // Custom side-effect after activity ingestion
  *         },
+ *         "sleeps": true,   // register route, default processing only
+ *         "dailies": true,
+ *       },
+ *       // Optional catch-all, runs for every registered event
+ *       onEvent: async (ctx, event) => {
+ *         console.log(`Garmin ${event.dataType}: ${event.items.length} items`);
  *       },
  *     },
  *   },
@@ -893,209 +602,10 @@ export class Soma {
 export function registerRoutes(http, component, opts) {
     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;
-                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;
-                try {
-                    result = await ctx.runAction(component.garmin.public.completeGarminOAuth, {
-                        code,
-                        state,
-                        clientId,
-                        clientSecret,
-                    });
-                }
-                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 ──────────────────────────────────
-        if (garminOpts.webhook !== false) {
-            const webhookCfg = typeof garminOpts.webhook === "object" ? garminOpts.webhook : {};
-            const webhookBase = webhookCfg.basePath ?? GARMIN_WEBHOOK_BASE_PATH;
-            const webhookRoutes = [
-                // 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) {
-                http.route({
-                    path: `${webhookBase}${route.suffix}`,
-                    method: "POST",
-                    handler: httpActionGeneric(async (ctx, request) => {
-                        let payload;
-                        try {
-                            payload = await request.json();
-                        }
-                        catch {
-                            return new Response("Invalid JSON body", { status: 400 });
-                        }
-                        let result;
-                        try {
-                            result = await ctx.runAction(route.action, { payload });
-                        }
-                        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 dataType = route.suffix.slice(1);
-                            const event = {
-                                dataType,
-                                processed: result.processed,
-                                errors: result.errors,
-                                affectedUsers: result.affectedUsers,
-                            };
-                            const specificHandler = webhookCfg.events?.[dataType];
-                            if (specificHandler) {
-                                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);
     }
 }
 //# sourceMappingURL=index.js.map