@nativesquare/soma 0.12.0 → 0.13.1

package/dist/client/strava.d.ts

@@ -1,5 +1,7 @@
 import type { SomaComponent } from "./index.js";
-import type { ActionCtx, SomaStravaConfig } from "./types.js";
+import type { ActionCtx, SomaStravaConfig, RegisterRoutesOptions } from "./types.js";
+import { type HttpRouter } from "convex/server";
+export declare const STRAVA_CALLBACK_PATH = "/api/strava/callback";
 export declare class SomaStrava {
     private component;
     private requireConfig;
@@ -13,7 +15,9 @@ export declare class SomaStrava {
      *
      * @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.redirectUri - The URL Strava will redirect to after authorization.
+     *   This should match the `registerRoutes` callback path
+     *   (default: `${CONVEX_SITE_URL}/api/strava/callback`).
      * @param opts.scope - Comma-separated Strava OAuth scopes (default: "read,activity:read_all,profile:read_all")
      * @returns `{ authUrl, state }`
      *
@@ -56,15 +60,17 @@ export declare class SomaStrava {
         userId: string;
         after?: number;
     }): Promise<{
+        data: {
+            synced: {
+                activities: number;
+                athletes: number;
+            };
+        };
         errors: Array<{
-            error: string;
             id: string;
+            message: string;
             type: string;
         }>;
-        synced: {
-            activities: number;
-            athletes: number;
-        };
     }>;
     /**
      * Disconnect a user from Strava.
@@ -88,5 +94,6 @@ export declare class SomaStrava {
     disconnect(ctx: ActionCtx, args: {
         userId: string;
     }): Promise<null>;
+    static registerRoutes(http: HttpRouter, component: SomaComponent, opts?: RegisterRoutesOptions["strava"]): void;
 }
 //# sourceMappingURL=strava.d.ts.map

package/dist/client/strava.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"strava.d.ts","sourceRoot":"","sources":["../../src/client/strava.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9D,qBAAa,UAAU;IAEnB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,aAAa;gBADb,SAAS,EAAE,aAAa,EACxB,aAAa,EAAE,MAAM,gBAAgB;IAG/C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,UAAU,CACd,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAW/D;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,IAAI,CACR,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;;;IAU1C;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CACd,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;CAS3B"}
+{"version":3,"file":"strava.d.ts","sourceRoot":"","sources":["../../src/client/strava.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,SAAS,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACrF,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAEnE,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D,qBAAa,UAAU;IAEnB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,aAAa;gBADb,SAAS,EAAE,aAAa,EACxB,aAAa,EAAE,MAAM,gBAAgB;IAG/C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,UAAU,CACd,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;IAW/D;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,IAAI,CACR,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE;;;;;;;;;;;;;IAU1C;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CACd,GAAG,EAAE,SAAS,EACd,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE;IAU1B,MAAM,CAAC,cAAc,CACnB,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,aAAa,EACxB,IAAI,CAAC,EAAE,qBAAqB,CAAC,QAAQ,CAAC;CAoFzC"}

package/dist/client/strava.js

@@ -1,3 +1,5 @@
+import { httpActionGeneric } from "convex/server";
+export const STRAVA_CALLBACK_PATH = "/api/strava/callback";
 export class SomaStrava {
     component;
     requireConfig;
@@ -14,7 +16,9 @@ export class SomaStrava {
      *
      * @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.redirectUri - The URL Strava will redirect to after authorization.
+     *   This should match the `registerRoutes` callback path
+     *   (default: `${CONVEX_SITE_URL}/api/strava/callback`).
      * @param opts.scope - Comma-separated Strava OAuth scopes (default: "read,activity:read_all,profile:read_all")
      * @returns `{ authUrl, state }`
      *
@@ -92,5 +96,67 @@ export class SomaStrava {
             clientSecret: config.clientSecret,
         });
     }
+    static registerRoutes(http, component, opts) {
+        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;
+                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,
+                });
+            }),
+        });
+    }
 }
 //# sourceMappingURL=strava.js.map

package/dist/client/strava.js.map

@@ -1 +1 @@
-{"version":3,"file":"strava.js","sourceRoot":"","sources":["../../src/client/strava.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,UAAU;IAEX;IACA;IAFV,YACU,SAAwB,EACxB,aAAqC;QADrC,cAAS,GAAT,SAAS,CAAe;QACxB,kBAAa,GAAb,aAAa,CAAwB;IAC5C,CAAC;IAEJ;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,UAAU,CACd,GAAc,EACd,IAA6D;QAE7D,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpC,OAAO,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE;YACxE,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;SACpB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,KAAK,CAAC,IAAI,CACR,GAAc,EACd,IAAwC;QAExC,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpC,OAAO,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE;YAClE,GAAG,IAAI;YACP,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,KAAK,CAAC,UAAU,CACd,GAAc,EACd,IAAwB;QAExB,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QACpC,OAAO,MAAM,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE;YACxE,GAAG,IAAI;YACP,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,YAAY,EAAE,MAAM,CAAC,YAAY;SAClC,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"strava.js","sourceRoot":"","sources":["../../src/client/strava.ts"],"names":[],"mappings":"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"}

package/dist/client/types.d.ts

@@ -28,6 +28,38 @@ export interface SomaGarminConfig {
     /** Your Garmin application's Client Secret. */
     clientSecret: string;
 }
+/**
+ * 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[];
+};
 /**
  * Common args shape for all ingestion methods.
  *
@@ -78,20 +110,49 @@ export interface GarminConnectEvent {
     userId: string;
     connectionId: string;
 }
-/** Data passed to webhook `events` handlers and `onEvent` after data ingestion. */
+/** Args accepted by all Garmin webhook handler actions inside the component. */
+export type GarminWebhookActionArgs = {
+    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;
-    processed: number;
-    errors: Array<{
-        type: string;
-        id: string;
-        error: string;
-    }>;
-    /** Users whose data was affected by this webhook. */
-    affectedUsers: Array<{
-        userId: string;
-        connectionId: 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";
@@ -103,10 +164,6 @@ export type GarminWebhookHandler = (ctx: GenericActionCtx<GenericDataModel>, eve
 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. */
@@ -115,10 +172,6 @@ export interface StravaOAuthOptions {
 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. */
@@ -127,6 +180,18 @@ export interface GarminOAuthOptions {
 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;
     /**
@@ -151,10 +216,18 @@ export interface GarminWebhookOptions {
 }
 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;
         /**

package/dist/client/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"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"}

package/dist/component/_generated/component.d.ts

@@ -156,54 +156,71 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         };
         webhooks: {
             handleGarminWebhookActivities: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookActivityDetails: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookBloodPressures: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookBodyCompositions: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookDailies: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookEpochs: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookHealthSnapshot: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookHRVSummary: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookManuallyUpdatedActivities: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookMenstrualCycleTracking: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookMoveIQ: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookPulseOx: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookRespiration: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookSkinTemp: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookSleeps: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookStress: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
             handleGarminWebhookUserMetrics: FunctionReference<"action", "internal", {
+                autoIngest?: boolean;
                 payload: any;
             }, any, Name>;
         };
@@ -1530,15 +1547,17 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
                 clientSecret: string;
                 userId: string;
             }, {
+                data: {
+                    synced: {
+                        activities: number;
+                        athletes: number;
+                    };
+                };
                 errors: Array<{
-                    error: string;
                     id: string;
+                    message: string;
                     type: string;
                 }>;
-                synced: {
-                    activities: number;
-                    athletes: number;
-                };
             }, Name>;
         };
     };