@nativesquare/soma 0.1.2 → 0.2.0

package/src/strava/index.ts

@@ -0,0 +1,54 @@
+// ─── @nativesquare/soma/strava ───────────────────────────────────────────────
+// Strava API → Soma schema transformers, API client, OAuth helpers, and sync.
+//
+// Pure TypeScript with zero runtime dependencies (uses global `fetch`).
+// Compatible with Convex actions and any modern runtime.
+
+// ── Transformers ─────────────────────────────────────────────────────────────
+export { transformActivity } from "./activity.js";
+export type { ActivityData } from "./activity.js";
+
+export { transformAthlete } from "./athlete.js";
+export type { AthleteData } from "./athlete.js";
+
+// ── Enum Maps ────────────────────────────────────────────────────────────────
+export { mapSportType } from "./maps/sport-type.js";
+
+// ── API Client ───────────────────────────────────────────────────────────────
+export { StravaClient, StravaApiError } from "./client.js";
+export type { StravaClientOptions } from "./client.js";
+
+// ── OAuth Helpers ────────────────────────────────────────────────────────────
+export { buildAuthUrl, exchangeCode, refreshToken } from "./auth.js";
+export type {
+  BuildAuthUrlOptions,
+  ExchangeCodeOptions,
+  RefreshTokenOptions,
+} from "./auth.js";
+
+// ── Sync Helpers ─────────────────────────────────────────────────────────────
+export { syncActivities, syncAthlete } from "./sync.js";
+export type {
+  SyncActivitiesOptions,
+  SyncActivitiesResult,
+  SyncAthleteOptions,
+} from "./sync.js";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+export type {
+  DetailedActivity,
+  DetailedAthlete,
+  Lap,
+  OAuthTokenResponse,
+  PolylineMap,
+  SegmentEffort,
+  Split,
+  Stream,
+  StreamSet,
+  StravaSportType,
+  SummaryActivity,
+  SummaryAthlete,
+  SummaryClub,
+  SummaryGear,
+  SummarySegment,
+} from "./types.js";

package/src/strava/maps/sport-type.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import { mapSportType } from "./sport-type.js";
+
+describe("mapSportType", () => {
+  it("maps cycling sport types to Terra Biking (1)", () => {
+    expect(mapSportType("Ride")).toBe(1);
+    expect(mapSportType("MountainBikeRide")).toBe(1);
+    expect(mapSportType("GravelRide")).toBe(1);
+    expect(mapSportType("EBikeRide")).toBe(1);
+    expect(mapSportType("EMountainBikeRide")).toBe(1);
+    expect(mapSportType("VirtualRide")).toBe(1);
+    expect(mapSportType("Velomobile")).toBe(1);
+  });
+
+  it("maps running sport types to Terra Running (8)", () => {
+    expect(mapSportType("Run")).toBe(8);
+    expect(mapSportType("TrailRun")).toBe(8);
+    expect(mapSportType("VirtualRun")).toBe(8);
+  });
+
+  it("maps Walk to Terra Walking (7)", () => {
+    expect(mapSportType("Walk")).toBe(7);
+  });
+
+  it("maps Swim to Terra Swimming (82)", () => {
+    expect(mapSportType("Swim")).toBe(82);
+  });
+
+  it("maps Hike to Terra Hiking (35)", () => {
+    expect(mapSportType("Hike")).toBe(35);
+  });
+
+  it("maps snow sports correctly", () => {
+    expect(mapSportType("AlpineSki")).toBe(66);
+    expect(mapSportType("NordicSki")).toBe(67);
+    expect(mapSportType("Snowboard")).toBe(73);
+    expect(mapSportType("Snowshoe")).toBe(74);
+  });
+
+  it("maps water sports correctly", () => {
+    expect(mapSportType("Rowing")).toBe(53);
+    expect(mapSportType("Kayaking")).toBe(40);
+    expect(mapSportType("Sail")).toBe(59);
+    expect(mapSportType("Surfing")).toBe(81);
+    expect(mapSportType("Kitesurf")).toBe(41);
+  });
+
+  it("maps racket sports correctly", () => {
+    expect(mapSportType("Tennis")).toBe(87);
+    expect(mapSportType("TableTennis")).toBe(85);
+    expect(mapSportType("Badminton")).toBe(10);
+    expect(mapSportType("Squash")).toBe(76);
+  });
+
+  it("maps gym/fitness activities correctly", () => {
+    expect(mapSportType("WeightTraining")).toBe(80);
+    expect(mapSportType("Crossfit")).toBe(113);
+    expect(mapSportType("Yoga")).toBe(100);
+    expect(mapSportType("Pilates")).toBe(49);
+    expect(mapSportType("HighIntensityIntervalTraining")).toBe(114);
+    expect(mapSportType("Elliptical")).toBe(25);
+    expect(mapSportType("StairStepper")).toBe(78);
+  });
+
+  it("returns Terra Other (108) for unknown types", () => {
+    expect(mapSportType("UnknownSport" as never)).toBe(108);
+    expect(mapSportType("" as never)).toBe(108);
+  });
+});

package/src/strava/maps/sport-type.ts

@@ -0,0 +1,99 @@
+// ─── Strava SportType → Terra ActivityType ───────────────────────────────────
+// Maps Strava sport_type strings to Terra's ActivityType numeric enum
+// used by the Soma schema.
+//
+// Strava values: https://developers.strava.com/docs/reference/#api-models-SportType
+// Terra values:  https://docs.tryterra.co/reference/health-and-fitness-api/data-models#activitytype
+
+import type { StravaSportType } from "../types.js";
+
+const sportTypeMap: Record<string, number> = {
+  // ── Cycling ────────────────────────────────────────────────────────────────
+  // Terra Biking = 1
+  Ride: 1,
+  MountainBikeRide: 1,
+  GravelRide: 1,
+  EBikeRide: 1,
+  EMountainBikeRide: 1,
+  VirtualRide: 1,
+  Velomobile: 1,
+
+  // ── Running ────────────────────────────────────────────────────────────────
+  // Terra Running = 8
+  Run: 8,
+  TrailRun: 8,
+  VirtualRun: 8,
+
+  // ── Walking ────────────────────────────────────────────────────────────────
+  // Terra Walking = 7
+  Walk: 7,
+
+  // ── Swimming ───────────────────────────────────────────────────────────────
+  // Terra Swimming = 82
+  Swim: 82,
+
+  // ── Hiking ─────────────────────────────────────────────────────────────────
+  // Terra Hiking = 35
+  Hike: 35,
+
+  // ── Snow Sports ────────────────────────────────────────────────────────────
+  AlpineSki: 66,          // Terra Alpine Skiing
+  BackcountrySki: 66,     // Terra Alpine Skiing
+  NordicSki: 67,          // Terra Cross Country Skiing
+  Snowboard: 73,          // Terra Snowboarding
+  Snowshoe: 74,           // Terra Snowshoeing
+
+  // ── Water Sports ───────────────────────────────────────────────────────────
+  Rowing: 53,             // Terra Rowing
+  VirtualRow: 53,         // Terra Rowing
+  Kayaking: 40,           // Terra Kayaking
+  Canoeing: 22,           // Terra Canoeing
+  Sail: 59,               // Terra Sailing
+  Surfing: 81,            // Terra Surfing
+  Kitesurf: 41,           // Terra Kitesurfing
+  Windsurf: 99,           // Terra Windsurfing
+  StandUpPaddling: 129,   // Terra Paddling
+
+  // ── Skating ────────────────────────────────────────────────────────────────
+  IceSkate: 62,           // Terra Skating
+  InlineSkate: 62,        // Terra Skating
+  Skateboard: 62,         // Terra Skating
+  RollerSki: 62,          // Terra Skating
+
+  // ── Racket Sports ──────────────────────────────────────────────────────────
+  Tennis: 87,             // Terra Tennis
+  TableTennis: 85,        // Terra Table Tennis
+  Badminton: 10,          // Terra Badminton
+  Racquetball: 51,        // Terra Racquetball
+  Squash: 76,             // Terra Squash
+  Pickleball: 108,        // Terra Other (no direct mapping)
+
+  // ── Gym / Fitness ──────────────────────────────────────────────────────────
+  WeightTraining: 80,     // Terra Strength Training
+  Crossfit: 113,          // Terra Crossfit
+  Elliptical: 25,         // Terra Elliptical
+  StairStepper: 78,       // Terra Stair Climbing Machine
+  Yoga: 100,              // Terra Yoga
+  Pilates: 49,            // Terra Pilates
+  HighIntensityIntervalTraining: 114, // Terra HIIT
+
+  // ── Climbing ───────────────────────────────────────────────────────────────
+  RockClimbing: 52,       // Terra Rock Climbing
+
+  // ── Team Sports ────────────────────────────────────────────────────────────
+  Soccer: 29,             // Terra English Football
+
+  // ── Other ──────────────────────────────────────────────────────────────────
+  Golf: 32,               // Terra Golf
+  Handcycle: 14,          // Terra Handbiking
+  Wheelchair: 98,         // Terra Wheelchair
+  Workout: 108,           // Terra Other
+};
+
+/**
+ * Map a Strava sport_type string to the Terra ActivityType enum.
+ * Returns Terra "Other" (108) for unknown types.
+ */
+export function mapSportType(sportType: StravaSportType): number {
+  return sportTypeMap[sportType] ?? 108;
+}

package/src/strava/sync.ts

@@ -0,0 +1,168 @@
+// ─── Strava Sync Helper ──────────────────────────────────────────────────────
+// High-level function that combines the Strava client, transformers,
+// and Soma ingestion into a single call. Designed to be used inside a
+// Convex action.
+
+import type { Soma } from "../client/index.js";
+import type { ActionCtx } from "../client/types.js";
+import type { StravaClient } from "./client.js";
+import { transformActivity } from "./activity.js";
+import { transformAthlete } from "./athlete.js";
+
+export interface SyncActivitiesOptions {
+  /** Authenticated Strava API client. */
+  client: StravaClient;
+  /** Soma component instance. */
+  soma: Soma;
+  /** Convex action context (has runMutation for ingestion). */
+  ctx: ActionCtx;
+  /** The Soma connection ID for this user–Strava link. */
+  connectionId: string;
+  /** The host app's user identifier (e.g., Clerk user ID). */
+  userId: string;
+  /**
+   * Only sync activities after this Unix epoch timestamp (seconds).
+   * Useful for incremental sync — pass the `lastDataUpdate` timestamp.
+   */
+  after?: number;
+  /**
+   * Only sync activities before this Unix epoch timestamp (seconds).
+   */
+  before?: number;
+  /**
+   * Fetch detailed streams (heart rate, power, position, etc.) for each
+   * activity. Adds one API call per activity.
+   * @default false
+   */
+  includeStreams?: boolean;
+  /**
+   * Fetch lap data for each activity. Adds one API call per activity
+   * (unless the detailed activity already contains laps).
+   * @default false
+   */
+  includeLaps?: boolean;
+}
+
+export interface SyncActivitiesResult {
+  /** Number of activities successfully synced. */
+  synced: number;
+  /** Activity IDs that failed to sync (non-fatal). */
+  errors: Array<{ activityId: number; error: string }>;
+}
+
+/**
+ * Sync activities from Strava into Soma.
+ *
+ * This function handles the full flow:
+ * 1. Lists activities from the Strava API (with auto-pagination)
+ * 2. Optionally fetches detailed data, streams, and laps per activity
+ * 3. Transforms each activity into the Soma schema
+ * 4. Ingests each activity into Soma (with automatic deduplication)
+ *
+ * Designed to be called from a Convex action.
+ *
+ * @example
+ * ```ts
+ * import { StravaClient, syncActivities } from "@nativesquare/soma/strava";
+ * import { Soma } from "@nativesquare/soma";
+ *
+ * export const syncStrava = internalAction({
+ *   args: { userId: v.string(), connectionId: v.string(), accessToken: v.string() },
+ *   handler: async (ctx, { userId, connectionId, accessToken }) => {
+ *     const client = new StravaClient({ accessToken });
+ *     const soma = new Soma(components.soma);
+ *
+ *     const result = await syncActivities({
+ *       client,
+ *       soma,
+ *       ctx,
+ *       connectionId,
+ *       userId,
+ *       includeStreams: true,
+ *     });
+ *
+ *     console.log(`Synced ${result.synced} activities`);
+ *   },
+ * });
+ * ```
+ */
+export async function syncActivities(
+  opts: SyncActivitiesOptions,
+): Promise<SyncActivitiesResult> {
+  const {
+    client,
+    soma,
+    ctx,
+    connectionId,
+    userId,
+    after,
+    before,
+    includeStreams = false,
+    includeLaps = false,
+  } = opts;
+
+  const summaries = await client.listAllActivities({
+    after,
+    before,
+  });
+
+  let synced = 0;
+  const errors: SyncActivitiesResult["errors"] = [];
+
+  for (const summary of summaries) {
+    try {
+      const detailed = await client.getActivity(summary.id);
+
+      const streams = includeStreams
+        ? await client.getActivityStreams(summary.id)
+        : undefined;
+
+      const laps =
+        includeLaps && (!detailed.laps || detailed.laps.length === 0)
+          ? await client.getActivityLaps(summary.id)
+          : undefined;
+
+      const data = transformActivity(detailed, { streams, laps });
+
+      await soma.ingestActivity(ctx, { connectionId, userId, ...data });
+      synced++;
+    } catch (err) {
+      errors.push({
+        activityId: summary.id,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
+  return { synced, errors };
+}
+
+export interface SyncAthleteOptions {
+  /** Authenticated Strava API client. */
+  client: StravaClient;
+  /** Soma component instance. */
+  soma: Soma;
+  /** Convex action context. */
+  ctx: ActionCtx;
+  /** The Soma connection ID for this user–Strava link. */
+  connectionId: string;
+  /** The host app's user identifier. */
+  userId: string;
+}
+
+/**
+ * Sync the authenticated athlete's profile from Strava into Soma.
+ *
+ * @example
+ * ```ts
+ * await syncAthlete({ client, soma, ctx, connectionId, userId });
+ * ```
+ */
+export async function syncAthlete(
+  opts: SyncAthleteOptions,
+): Promise<void> {
+  const { client, soma, ctx, connectionId, userId } = opts;
+  const athlete = await client.getAthlete();
+  const data = transformAthlete(athlete);
+  await soma.ingestAthlete(ctx, { connectionId, userId, ...data });
+}