@nativesquare/soma 0.17.0 → 0.18.0

package/src/client/types.ts

@@ -234,7 +234,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 +318,31 @@ 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.
+     *
+     * @default true
+     */
+    autoIngest?: 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 +351,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 +398,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 +407,34 @@ 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 }` pair. `true` becomes a no-handler
+ * config with auto-ingest enabled; the object form fills in defaults.
+ */
+export function resolveEventConfig<H>(
+  entry: true | { handler?: H; autoIngest?: boolean } | undefined,
+): { handler: H | undefined; autoIngest: boolean } {
+  if (entry === undefined || entry === true) {
+    return { handler: undefined, autoIngest: true };
+  }
+  return { handler: entry.handler, autoIngest: entry.autoIngest ?? true };
 }
 
 export interface RegisterRoutesOptions {

package/src/component/_generated/component.ts

@@ -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;