@nativesquare/soma 0.17.1 → 0.18.1

package/src/client/garmin.ts

@@ -8,6 +8,7 @@ import type {
   GarminWebhookEventName,
   GarminWebhookEvent,
 } from "./types.js";
+import { resolveEventConfig } from "./types.js";
 import {
   httpActionGeneric,
   type FunctionReference,
@@ -705,8 +706,6 @@ export class SomaGarmin {
     if (webhookCfg?.events) {
       const webhookBase = webhookCfg.basePath ?? GARMIN_WEBHOOK_BASE_PATH;
 
-      const autoIngest = webhookCfg.autoIngest ?? true;
-
       const webhookRoutes: Array<{
         dataType: GarminWebhookEventName;
         action: FunctionReference<"action", "internal", GarminWebhookActionArgs, GarminWebhookActionResult>;
@@ -739,7 +738,19 @@ export class SomaGarmin {
         const { dataType } = route;
 
         // Only register routes the host app explicitly opted into
-        if (!webhookCfg.events?.[dataType]) continue;
+        const entry = webhookCfg.events?.[dataType];
+        if (!entry) continue;
+
+        const { handler: specificHandler, autoIngest, rawPassthrough } =
+          resolveEventConfig(entry);
+
+        if (autoIngest && rawPassthrough) {
+          throw new Error(
+            `[soma:garmin:webhook] events["${dataType}"] cannot enable both ` +
+            `autoIngest and rawPassthrough — raw Garmin items can't be ` +
+            `auto-ingested into Soma's normalized schema. Set autoIngest: false.`,
+          );
+        }
 
         http.route({
           path: `${webhookBase}/${dataType}`,
@@ -764,7 +775,11 @@ export class SomaGarmin {
 
             let result: GarminWebhookActionResult | undefined;
             try {
-              result = await ctx.runAction(route.action, { payload, autoIngest });
+              result = await ctx.runAction(route.action, {
+                payload,
+                autoIngest,
+                rawPassthrough,
+              });
             } catch (error) {
               // Log but return 200 to prevent Garmin from retrying
               console.error(
@@ -784,8 +799,7 @@ export class SomaGarmin {
                 items: result.items,
               };
 
-              const specificHandler = webhookCfg.events?.[dataType];
-              if (typeof specificHandler === "function") {
+              if (specificHandler) {
                 try {
                   await specificHandler(ctx, event);
                 } catch (callbackError) {

package/src/client/strava.ts

@@ -6,7 +6,9 @@ import type {
   StravaWebhookActionResult,
   StravaWebhookEvent,
   StravaWebhookEventName,
+  StravaWebhookHandler,
 } from "./types.js";
+import { resolveEventConfig } from "./types.js";
 import { httpActionGeneric, type HttpRouter } from "convex/server";
 
 export const STRAVA_OAUTH_CALLBACK_PATH = "/api/strava/callback";
@@ -324,7 +326,19 @@ export class SomaStrava {
     if (webhookCfg?.events) {
       const webhookPath = webhookCfg.path ?? STRAVA_WEBHOOK_BASE_PATH;
       const verifyToken = webhookCfg.verifyToken ?? process.env.STRAVA_WEBHOOK_VERIFY_TOKEN;
-      const autoIngest = webhookCfg.autoIngest ?? true;
+
+      // Resolve each registered event into its handler + autoIngest pair once,
+      // up-front. The dispatcher action receives `autoIngestByEvent` and the
+      // POST handler reuses `handlersByEvent` for per-event callback dispatch.
+      const autoIngestByEvent: Partial<Record<StravaWebhookEventName, boolean>> = {};
+      const handlersByEvent: Partial<Record<StravaWebhookEventName, StravaWebhookHandler>> = {};
+      for (const [eventName, entry] of Object.entries(webhookCfg.events) as Array<
+        [StravaWebhookEventName, typeof webhookCfg.events[StravaWebhookEventName]]
+      >) {
+        const { handler, autoIngest } = resolveEventConfig(entry);
+        autoIngestByEvent[eventName] = autoIngest;
+        if (handler) handlersByEvent[eventName] = handler;
+      }
 
       // GET: Strava subscription verification challenge
       http.route({
@@ -403,7 +417,12 @@ export class SomaStrava {
           try {
             result = await ctx.runAction(
               component.strava.webhooks.handleStravaWebhook,
-              { payload, clientId: webhookClientId, clientSecret: webhookClientSecret, autoIngest },
+              {
+                payload,
+                clientId: webhookClientId,
+                clientSecret: webhookClientSecret,
+                autoIngestByEvent,
+              },
             );
           } catch (error) {
             console.error(
@@ -424,8 +443,8 @@ export class SomaStrava {
             };
 
             // Fire per-event handler
-            const specificHandler = webhookCfg.events?.[eventName];
-            if (typeof specificHandler === "function") {
+            const specificHandler = handlersByEvent[eventName];
+            if (specificHandler) {
               try {
                 await specificHandler(ctx, event);
               } catch (callbackError) {

package/src/client/types.ts

@@ -153,6 +153,7 @@ export type GarminWebhookActionArgs = {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   payload: any;
   autoIngest?: boolean;
+  rawPassthrough?: boolean;
 };
 
 /** Result returned by all Garmin webhook handler actions inside the component. */
@@ -167,7 +168,16 @@ export interface GarminWebhookItem {
   connectionId: string;
   /** The host app's user ID. */
   userId: string;
-  /** The transformed data in Soma's normalized format, or null for terminal events like deregistration. */
+  /**
+   * The data for this item.
+   *
+   * - In the default mode, this is the data in Soma's normalized format
+   *   (the result of `transformX(rawItem)`).
+   * - When the event was registered with `rawPassthrough: true`, this is the
+   *   raw Garmin item exactly as received (post zod validation), so the host
+   *   app can act on the provider's native shape.
+   * - `null` for terminal events like deregistration.
+   */
   data: Record<string, unknown> | null;
 }
 
@@ -234,7 +244,12 @@ export type StravaWebhookActionArgs = {
   };
   clientId: string;
   clientSecret: string;
-  autoIngest?: boolean;
+  /**
+   * Per-event override of the auto-ingest flag. The dispatcher resolves the
+   * event name from the payload and looks up the flag here. Defaults to `true`
+   * for any event missing from the map.
+   */
+  autoIngestByEvent?: Partial<Record<StravaWebhookEventName, boolean>>;
 };
 
 /** Result returned by the Strava webhook handler action inside the component. */
@@ -313,21 +328,48 @@ export interface GarminOAuthOptions {
   ) => Promise<void>;
 }
 
+/**
+ * Configuration for a single Garmin webhook data type.
+ *
+ * Pass `true` as a shortcut for "register the route with default processing
+ * and `autoIngest: true`". Pass an object to customize per-type behavior.
+ */
+export type GarminWebhookEventConfig =
+  | true
+  | {
+    /** Custom logic to run after the payload is processed. */
+    handler?: GarminWebhookHandler;
+    /**
+     * Whether the component should auto-write the transformed data to the
+     * Soma database for this data type. When `false`, the payload is still
+     * validated and transformed (and surfaced to `handler` / `onEvent`), but
+     * the DB write is skipped so the host app can ingest it itself.
+     *
+     * Cannot be `true` simultaneously with `rawPassthrough: true` — raw
+     * provider items can't be auto-ingested into Soma's normalized schema.
+     *
+     * @default true
+     */
+    autoIngest?: boolean;
+    /**
+     * When `true`, skip Soma's `transformX(rawItem)` step and surface the
+     * raw Garmin item directly in `items[].data`. Soma still parses the
+     * payload with zod and resolves Garmin `userId` → Soma
+     * `connectionId`/`userId`, so the host app gets raw Garmin data already
+     * keyed to its own users.
+     *
+     * Implies `autoIngest: false` — raw items cannot be auto-ingested into
+     * Soma's normalized schema. Setting `autoIngest: true` alongside
+     * `rawPassthrough: true` throws at route registration time.
+     *
+     * @default false
+     */
+    rawPassthrough?: boolean;
+  };
+
 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;
   /**
@@ -336,21 +378,44 @@ export interface GarminWebhookOptions {
    * **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.
+   * Pass `true` as a shortcut for default processing with auto-ingest, or
+   * an object to attach a handler and/or override `autoIngest`.
    *
    * @example
    * ```ts
    * events: {
-   *   "activities": async (ctx, event) => { // custom side-effect },
-   *   "sleeps": true,   // register route, default processing only
-   *   "dailies": true,
+   *   activities: { handler: async (ctx, event) => { /* side-effect *\/ } },
+   *   sleeps: true,                                 // default processing
+   *   dailies: { autoIngest: false },               // skip DB write
+   *   "body-compositions": { autoIngest: false, handler: customHandler },
    * }
    * ```
    */
-  events?: Partial<Record<GarminWebhookEventName, GarminWebhookHandler | true>>;
+  events?: Partial<Record<GarminWebhookEventName, GarminWebhookEventConfig>>;
 }
 
+/**
+ * Configuration for a single Strava webhook event.
+ *
+ * Pass `true` as a shortcut for "process this event with default behavior and
+ * `autoIngest: true`". Pass an object to customize per-event behavior.
+ */
+export type StravaWebhookEventConfig =
+  | true
+  | {
+    /** Custom logic to run after the event is processed. */
+    handler?: StravaWebhookHandler;
+    /**
+     * Whether the component should auto-write the transformed data to the
+     * Soma database for this event. When `false`, the payload is still
+     * fetched and transformed (and surfaced to `handler` / `onEvent`), but
+     * the DB write is skipped so the host app can ingest it itself.
+     *
+     * @default true
+     */
+    autoIngest?: boolean;
+  };
+
 export interface StravaWebhookOptions {
   /** HTTP path for the webhook endpoint. @default "/api/strava/webhook" */
   path?: string;
@@ -360,17 +425,6 @@ export interface StravaWebhookOptions {
    * Falls back to `STRAVA_WEBHOOK_VERIFY_TOKEN` env var.
    */
   verifyToken?: string;
-  /**
-   * Whether to automatically ingest transformed data into the Soma database.
-   *
-   * When `true` (default), fetched data is transformed and written to the
-   * database automatically. When `false`, the webhook still fetches and
-   * transforms the data, but skips the database write — useful when you want
-   * to handle ingestion yourself via the `onEvent` / per-event callbacks.
-   *
-   * @default true
-   */
-  autoIngest?: boolean;
   /** Called after every webhook event is processed, regardless of event type. */
   onEvent?: StravaWebhookHandler;
   /**
@@ -380,20 +434,42 @@ export interface StravaWebhookOptions {
    * events to a single endpoint. **Only event types listed here are processed.**
    * Unlisted event types are silently ignored (200 returned, no processing).
    *
-   * Pass a handler function for custom logic after processing,
-   * or `true` to enable default processing for that event type.
+   * Pass `true` as a shortcut for default processing with auto-ingest, or an
+   * object to attach a handler and/or override `autoIngest`.
    *
    * @example
    * ```ts
    * events: {
-   *   "activity-create": async (ctx, event) => { // custom side-effect },
-   *   "activity-update": true,   // default processing only
-   *   "athlete-update": true,
+   *   "activity-create": { handler: async (ctx, event) => { /* side-effect *\/ } },
+   *   "activity-update": true,                       // default processing
+   *   "athlete-update": { autoIngest: false },       // skip DB write
    *   "athlete-deauthorize": true,
    * }
    * ```
    */
-  events?: Partial<Record<StravaWebhookEventName, StravaWebhookHandler | true>>;
+  events?: Partial<Record<StravaWebhookEventName, StravaWebhookEventConfig>>;
+}
+
+/**
+ * Narrow a `GarminWebhookEventConfig` / `StravaWebhookEventConfig` value into
+ * its resolved `{ handler, autoIngest, rawPassthrough }` triple. `true`
+ * becomes a no-handler config with auto-ingest enabled and no passthrough;
+ * the object form fills in defaults.
+ *
+ * `rawPassthrough` is a Garmin-only concept today. Strava call-sites supply
+ * entries without the field, which resolves to `false` — a safe default.
+ */
+export function resolveEventConfig<H>(
+  entry: true | { handler?: H; autoIngest?: boolean; rawPassthrough?: boolean } | undefined,
+): { handler: H | undefined; autoIngest: boolean; rawPassthrough: boolean } {
+  if (entry === undefined || entry === true) {
+    return { handler: undefined, autoIngest: true, rawPassthrough: false };
+  }
+  return {
+    handler: entry.handler,
+    autoIngest: entry.autoIngest ?? true,
+    rawPassthrough: entry.rawPassthrough ?? false,
+  };
 }
 
 export interface RegisterRoutesOptions {

package/src/component/_generated/component.ts

@@ -296,126 +296,126 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         handleGarminWebhookActivities: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookActivityDetails: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookBloodPressures: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookBodyCompositions: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookDailies: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookDeregistration: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookEpochs: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookHealthSnapshot: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookHRVSummary: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookManuallyUpdatedActivities: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookMenstrualCycleTracking: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookMoveIQ: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookPulseOx: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookRespiration: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookSkinTemp: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookSleeps: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookStress: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
         handleGarminWebhookUserMetrics: FunctionReference<
           "action",
           "internal",
-          { autoIngest?: boolean; payload: any },
+          { autoIngest?: boolean; payload: any; rawPassthrough?: boolean },
           any,
           Name
         >;
@@ -2371,7 +2371,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           "action",
           "internal",
           {
-            autoIngest?: boolean;
+            autoIngestByEvent?: Record<string, boolean>;
             clientId: string;
             clientSecret: string;
             payload: any;