@nativesquare/soma 0.13.0 → 0.14.0

package/src/client/strava.ts

@@ -1,14 +1,22 @@
 import type { SomaComponent } from "./index.js";
-import type { ActionCtx, SomaStravaConfig, RegisterRoutesOptions } from "./types.js";
+import type {
+  ActionCtx,
+  SomaStravaConfig,
+  RegisterRoutesOptions,
+  StravaWebhookActionResult,
+  StravaWebhookEvent,
+  StravaWebhookEventName,
+} from "./types.js";
 import { httpActionGeneric, type HttpRouter } from "convex/server";
 
-export const STRAVA_CALLBACK_PATH = "/api/strava/callback";
+export const STRAVA_OAUTH_CALLBACK_PATH = "/api/strava/callback";
+export const STRAVA_WEBHOOK_BASE_PATH = "/api/strava/webhook";
 
 export class SomaStrava {
   constructor(
     private component: SomaComponent,
     private requireConfig: () => SomaStravaConfig,
-  ) {}
+  ) { }
 
   /**
    * Generate a Strava OAuth authorization URL.
@@ -19,7 +27,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 }`
    *
@@ -46,32 +56,30 @@ export class SomaStrava {
   }
 
   /**
-   * Sync activities from Strava for an already-connected user.
+   * Disconnect a user from Strava.
    *
-   * Automatically refreshes the access token if expired. Fetches the
-   * athlete profile and activities, transforms them, and ingests into Soma.
+   * 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
-   * @param args.after - Only sync activities after this Unix epoch timestamp (for incremental sync)
-   * @returns `{ synced, errors }`
    *
    * @example
    * ```ts
-   * export const syncStrava = action({
+   * export const disconnectStrava = action({
    *   args: { userId: v.string() },
    *   handler: async (ctx, { userId }) => {
-   *     return await soma.strava.sync(ctx, { userId });
+   *     await soma.strava.disconnect(ctx, { userId });
    *   },
    * });
    * ```
    */
-  async sync(
+  async disconnect(
     ctx: ActionCtx,
-    args: { userId: string; after?: number },
+    args: { userId: string },
   ) {
     const config = this.requireConfig();
-    return await ctx.runAction(this.component.strava.public.syncStrava, {
+    return await ctx.runAction(this.component.strava.public.disconnectStrava, {
       ...args,
       clientId: config.clientId,
       clientSecret: config.clientSecret,
@@ -79,30 +87,78 @@ export class SomaStrava {
   }
 
   /**
-   * Disconnect a user from Strava.
+   * Pull the authenticated athlete profile from Strava.
    *
-   * Revokes the token at Strava (best-effort), deletes stored tokens,
-   * and sets the connection to inactive.
+   * Automatically refreshes the access token if expired.
    *
    * @param ctx - Action context from the host app
    * @param args.userId - The host app's user identifier
+   */
+  async pullAthlete(
+    ctx: ActionCtx,
+    args: { userId: string },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.strava.public.pullAthlete, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull activities from Strava.
+   *
+   * Fetches activities, transforms them into the normalized Soma schema,
+   * and ingests them with automatic deduplication.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.after - Only pull activities after this Unix epoch timestamp
+   * @param args.before - Only pull activities before this Unix epoch timestamp
+   */
+  async pullActivities(
+    ctx: ActionCtx,
+    args: {
+      userId: string;
+      after?: number;
+      before?: number;
+    },
+  ) {
+    const config = this.requireConfig();
+    return await ctx.runAction(this.component.strava.public.pullActivities, {
+      ...args,
+      clientId: config.clientId,
+      clientSecret: config.clientSecret,
+    });
+  }
+
+  /**
+   * Pull all supported data types from Strava in a single call.
+   *
+   * Equivalent to calling `pullAthlete` and `pullActivities`. Automatically
+   * refreshes the access token if expired.
+   *
+   * @param ctx - Action context from the host app
+   * @param args.userId - The host app's user identifier
+   * @param args.after - Only pull activities after this Unix epoch timestamp
+   * @param args.before - Only pull activities before this Unix epoch timestamp
    *
    * @example
    * ```ts
-   * export const disconnectStrava = action({
-   *   args: { userId: v.string() },
-   *   handler: async (ctx, { userId }) => {
-   *     await soma.strava.disconnect(ctx, { userId });
-   *   },
-   * });
+   * await soma.strava.pullAll(ctx, { userId: "user_123" });
    * ```
    */
-  async disconnect(
+  async pullAll(
     ctx: ActionCtx,
-    args: { userId: string },
+    args: {
+      userId: string;
+      after?: number;
+      before?: number;
+    },
   ) {
     const config = this.requireConfig();
-    return await ctx.runAction(this.component.strava.public.disconnectStrava, {
+    return await ctx.runAction(this.component.strava.public.pullAll, {
       ...args,
       clientId: config.clientId,
       clientSecret: config.clientSecret,
@@ -115,7 +171,7 @@ export class SomaStrava {
     opts?: RegisterRoutesOptions["strava"],
   ) {
     const oauth = opts?.oauth ?? {};
-    const path = oauth.path ?? STRAVA_CALLBACK_PATH;
+    const path = oauth.path ?? STRAVA_OAUTH_CALLBACK_PATH;
 
     http.route({
       path,
@@ -195,5 +251,115 @@ export class SomaStrava {
         });
       }),
     });
+
+    // ── Strava Webhook Routes ──────────────────────────────────────
+    const webhookCfg = typeof opts?.webhook === "object" ? opts.webhook : undefined;
+    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;
+
+      // GET: Strava subscription verification challenge
+      http.route({
+        path: webhookPath,
+        method: "GET",
+        handler: httpActionGeneric(async (_ctx, request) => {
+          const url = new URL(request.url);
+          const mode = url.searchParams.get("hub.mode");
+          const challenge = url.searchParams.get("hub.challenge");
+          const token = url.searchParams.get("hub.verify_token");
+
+          if (mode === "subscribe" && token === verifyToken && challenge) {
+            return new Response(
+              JSON.stringify({ "hub.challenge": challenge }),
+              { status: 200, headers: { "Content-Type": "application/json" } },
+            );
+          }
+
+          return new Response("Forbidden", { status: 403 });
+        }),
+      });
+
+      // POST: Strava webhook event
+      http.route({
+        path: webhookPath,
+        method: "POST",
+        handler: httpActionGeneric(async (ctx, request) => {
+          let payload: unknown;
+          try {
+            payload = await request.json();
+          } catch {
+            return new Response("Invalid JSON body", { status: 400 });
+          }
+
+          // Determine event name and check if it's registered
+          const p = payload as { object_type?: string; aspect_type?: string };
+          const eventName = `${p.object_type}-${p.aspect_type}` as StravaWebhookEventName;
+
+          if (!webhookCfg.events?.[eventName]) {
+            // Event type not registered — silently ignore
+            return new Response("OK", { status: 200 });
+          }
+
+          const webhookClientId = opts?.clientId ?? process.env.STRAVA_CLIENT_ID;
+          const webhookClientSecret = opts?.clientSecret ?? process.env.STRAVA_CLIENT_SECRET;
+
+          if (!webhookClientId || !webhookClientSecret) {
+            console.error("[soma] Strava webhook: missing client credentials");
+            return new Response("OK", { status: 200 });
+          }
+
+          let result: StravaWebhookActionResult | undefined;
+          try {
+            result = await ctx.runAction(
+              component.strava.webhooks.handleStravaWebhook,
+              { payload, clientId: webhookClientId, clientSecret: webhookClientSecret, autoIngest },
+            );
+          } catch (error) {
+            console.error(
+              "[soma] Strava webhook error:",
+              error instanceof Error ? error.message : error,
+            );
+          }
+
+          if (result) {
+            const event: StravaWebhookEvent = {
+              eventName,
+              errors: result.errors,
+              rawPayload: payload,
+              items: result.items,
+            };
+
+            // Fire per-event handler
+            const specificHandler = webhookCfg.events?.[eventName];
+            if (typeof specificHandler === "function") {
+              try {
+                await specificHandler(ctx, event);
+              } catch (callbackError) {
+                console.error(
+                  `[soma] strava webhook events["${eventName}"] callback error:`,
+                  callbackError instanceof Error ? callbackError.message : callbackError,
+                );
+              }
+            }
+
+            // Fire catch-all handler
+            if (webhookCfg.onEvent) {
+              try {
+                await webhookCfg.onEvent(ctx, event);
+              } catch (callbackError) {
+                console.error(
+                  "[soma] strava webhook onEvent callback error:",
+                  callbackError instanceof Error ? callbackError.message : callbackError,
+                );
+              }
+            }
+          }
+
+          // Always return 200 to prevent Strava retries
+          return new Response("OK", { status: 200 });
+        }),
+      });
+    }
   }
 }

package/src/client/types.ts

@@ -208,6 +208,79 @@ export type GarminWebhookHandler = (
   event: GarminWebhookEvent,
 ) => Promise<void>;
 
+// ─── Strava Webhook Types ───────────────────────────────────────────────────
+
+/** Strava webhook event type names (object_type + aspect_type combined). */
+export type StravaWebhookEventName =
+  | "activity-create"
+  | "activity-update"
+  | "activity-delete"
+  | "athlete-update"
+  | "athlete-deauthorize";
+
+/** Args accepted by the Strava webhook handler action inside the component. */
+export type StravaWebhookActionArgs = {
+  payload: {
+    object_type: string;
+    object_id: number;
+    aspect_type: string;
+    owner_id: number;
+    subscription_id: number;
+    event_time: number;
+    updates?: Record<string, unknown>;
+  };
+  clientId: string;
+  clientSecret: string;
+  autoIngest?: boolean;
+};
+
+/** Result returned by the Strava webhook handler action inside the component. */
+export interface StravaWebhookActionResult {
+  errors: SomaError[];
+  items: StravaWebhookItem[];
+}
+
+/** A single transformed item from a Strava webhook, with user/connection mapping. */
+export interface StravaWebhookItem {
+  /** 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, or null for delete/deauthorize events. */
+  data: Record<string, unknown> | null;
+}
+
+/**
+ * Event data passed to Strava webhook handlers after processing.
+ *
+ * The host app receives the full set of transformed items plus the raw Strava
+ * notification payload, regardless of the `autoIngest` setting.
+ */
+export interface StravaWebhookEvent {
+  /** The combined event name (e.g. `"activity-create"`, `"athlete-deauthorize"`). */
+  eventName: StravaWebhookEventName;
+  /** Errors encountered during connection resolution, data fetching, or transformation. */
+  errors: SomaError[];
+  /** The raw Strava webhook notification payload. */
+  rawPayload: unknown;
+  /**
+   * Transformed items in Soma's normalized format.
+   *
+   * For `activity-create` / `activity-update` / `athlete-update`, contains the
+   * fetched and transformed data. For `activity-delete` / `athlete-deauthorize`,
+   * items have `data: null`.
+   *
+   * When `autoIngest` is `true`, these are the same items written to the database.
+   */
+  items: StravaWebhookItem[];
+}
+
+/** Handler for a specific Strava webhook event or the catch-all `onEvent`. */
+export type StravaWebhookHandler = (
+  ctx: GenericActionCtx<GenericDataModel>,
+  event: StravaWebhookEvent,
+) => Promise<void>;
+
 // ─── Route Registration Options ─────────────────────────────────────────────
 
 /**
@@ -275,6 +348,51 @@ export interface GarminWebhookOptions {
   events?: Partial<Record<GarminWebhookEventName, GarminWebhookHandler | true>>;
 }
 
+export interface StravaWebhookOptions {
+  /** HTTP path for the webhook endpoint. @default "/api/strava/webhook" */
+  path?: string;
+  /**
+   * Strava webhook subscription verify token.
+   * Must match the token used when creating the subscription via Strava's API.
+   * 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;
+  /**
+   * Per-event-type webhook handlers.
+   *
+   * Unlike Garmin (which registers per-type HTTP routes), Strava sends all
+   * 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.
+   *
+   * @example
+   * ```ts
+   * events: {
+   *   "activity-create": async (ctx, event) => { // custom side-effect },
+   *   "activity-update": true,   // default processing only
+   *   "athlete-update": true,
+   *   "athlete-deauthorize": true,
+   * }
+   * ```
+   */
+  events?: Partial<Record<StravaWebhookEventName, StravaWebhookHandler | true>>;
+}
+
 export interface RegisterRoutesOptions {
   strava?: {
     /** Override STRAVA_CLIENT_ID env var. */
@@ -283,6 +401,13 @@ export interface RegisterRoutesOptions {
     clientSecret?: string;
     /** OAuth callback configuration. */
     oauth?: StravaOAuthOptions;
+    /**
+     * Webhook configuration.
+     *
+     * Disabled by default. Only event types listed in `events` are processed.
+     * Omit entirely or set to `false` to skip webhook routes.
+     */
+    webhook?: StravaWebhookOptions | false;
   };
   garmin?: {
     /** Override GARMIN_CLIENT_ID env var. */

package/src/component/_generated/api.ts

@@ -59,7 +59,6 @@ import type * as private_ from "../private.js";
 import type * as public_ from "../public.js";
 import type * as strava_auth from "../strava/auth.js";
 import type * as strava_client from "../strava/client.js";
-import type * as strava_private from "../strava/private.js";
 import type * as strava_public from "../strava/public.js";
 import type * as strava_transform_activity from "../strava/transform/activity.js";
 import type * as strava_transform_athlete from "../strava/transform/athlete.js";
@@ -67,6 +66,7 @@ import type * as strava_transform_maps_sportType from "../strava/transform/maps/
 import type * as strava_types_stravaApi_client_index from "../strava/types/stravaApi/client/index.js";
 import type * as strava_types_stravaApi_index from "../strava/types/stravaApi/index.js";
 import type * as strava_utils from "../strava/utils.js";
+import type * as strava_webhooks from "../strava/webhooks.js";
 import type * as utils from "../utils.js";
 import type * as validators_activity from "../validators/activity.js";
 import type * as validators_athlete from "../validators/athlete.js";
@@ -141,7 +141,6 @@ const fullApi: ApiFromModules<{
   public: typeof public_;
   "strava/auth": typeof strava_auth;
   "strava/client": typeof strava_client;
-  "strava/private": typeof strava_private;
   "strava/public": typeof strava_public;
   "strava/transform/activity": typeof strava_transform_activity;
   "strava/transform/athlete": typeof strava_transform_athlete;
@@ -149,6 +148,7 @@ const fullApi: ApiFromModules<{
   "strava/types/stravaApi/client/index": typeof strava_types_stravaApi_client_index;
   "strava/types/stravaApi/index": typeof strava_types_stravaApi_index;
   "strava/utils": typeof strava_utils;
+  "strava/webhooks": typeof strava_webhooks;
   utils: typeof utils;
   "validators/activity": typeof validators_activity;
   "validators/athlete": typeof validators_athlete;

package/src/component/_generated/component.ts

@@ -1844,32 +1844,51 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           any,
           Name
         >;
-        syncAllTypes: FunctionReference<
+        pullActivities: FunctionReference<
           "action",
           "internal",
           {
-            accessToken: string;
             after?: number;
             before?: number;
-            connectionId: string;
+            clientId: string;
+            clientSecret: string;
             userId: string;
           },
           any,
           Name
         >;
-        syncStrava: FunctionReference<
+        pullAll: FunctionReference<
           "action",
           "internal",
           {
             after?: number;
+            before?: number;
             clientId: string;
             clientSecret: string;
             userId: string;
           },
+          any,
+          Name
+        >;
+        pullAthlete: FunctionReference<
+          "action",
+          "internal",
+          { clientId: string; clientSecret: string; userId: string },
+          any,
+          Name
+        >;
+      };
+      webhooks: {
+        handleStravaWebhook: FunctionReference<
+          "action",
+          "internal",
           {
-            data: { synced: { activities: number; athletes: number } };
-            errors: Array<{ id: string; message: string; type: string }>;
+            autoIngest?: boolean;
+            clientId: string;
+            clientSecret: string;
+            payload: any;
           },
+          any,
           Name
         >;
       };

package/src/component/garmin/auth.ts

@@ -2,6 +2,8 @@
 // Pure helper functions for the Garmin OAuth 2.0 PKCE flow.
 // Uses the Web Crypto API for SHA-256 challenge generation and global `fetch`.
 
+import type { OAuthRefreshResult } from "../utils.js";
+
 export interface GarminOAuth2TokenResponse {
   access_token: string;
   refresh_token: string;
@@ -158,7 +160,7 @@ export interface RefreshTokenOptions {
  */
 export async function refreshToken(
   opts: RefreshTokenOptions,
-): Promise<GarminOAuth2TokenResponse> {
+): Promise<OAuthRefreshResult> {
   const body = new URLSearchParams({
     grant_type: "refresh_token",
     client_id: opts.clientId,
@@ -179,5 +181,10 @@ export async function refreshToken(
     );
   }
 
-  return (await response.json()) as GarminOAuth2TokenResponse;
+  const raw = (await response.json()) as GarminOAuth2TokenResponse;
+  return {
+    access_token: raw.access_token,
+    refresh_token: raw.refresh_token,
+    expiresAt: Math.floor(Date.now() / 1000) + raw.expires_in,
+  };
 }