@nativesquare/soma 0.9.3 → 0.10.0

package/src/strava/client.ts

@@ -1,212 +0,0 @@
-// ─── Strava API Client ───────────────────────────────────────────────────────
-// Lightweight, fetch-based client for the Strava API v3.
-// No external dependencies — uses the global `fetch` available in Convex
-// actions and modern runtimes.
-
-import type {
-  DetailedActivity,
-  DetailedAthlete,
-  Lap,
-  StreamSet,
-  Stream,
-  SummaryActivity,
-} from "./types.js";
-
-const DEFAULT_BASE_URL = "https://www.strava.com";
-const API_PREFIX = "/api/v3";
-
-export interface StravaClientOptions {
-  /** OAuth access token for the authenticated athlete. */
-  accessToken: string;
-  /**
-   * Base URL of the Strava API (without `/api/v3` suffix).
-   * Defaults to `https://www.strava.com`.
-   * Override to point at a mock server during development.
-   */
-  baseUrl?: string;
-}
-
-/**
- * A lightweight client for the Strava API v3.
- *
- * @example
- * ```ts
- * const client = new StravaClient({
- *   accessToken: "tok_xxx",
- *   baseUrl: "https://strava-mock-server.onrender.com", // optional
- * });
- *
- * const athlete = await client.getAthlete();
- * const activities = await client.listActivities({ per_page: 50 });
- * ```
- */
-export class StravaClient {
-  private readonly accessToken: string;
-  private readonly baseUrl: string;
-
-  constructor(opts: StravaClientOptions) {
-    this.accessToken = opts.accessToken;
-    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
-  }
-
-  // ─── Athlete ─────────────────────────────────────────────────────────────
-
-  /**
-   * Get the authenticated athlete's profile.
-   *
-   * Strava API: `GET /athlete`
-   */
-  async getAthlete(): Promise<DetailedAthlete> {
-    return this.get<DetailedAthlete>("/athlete");
-  }
-
-  // ─── Activities ──────────────────────────────────────────────────────────
-
-  /**
-   * List the authenticated athlete's activities.
-   *
-   * Strava API: `GET /athlete/activities`
-   *
-   * @param params.before - Only return activities before this Unix epoch timestamp
-   * @param params.after - Only return activities after this Unix epoch timestamp
-   * @param params.page - Page number (defaults to 1)
-   * @param params.per_page - Items per page (defaults to 30, max 200)
-   */
-  async listActivities(params?: {
-    before?: number;
-    after?: number;
-    page?: number;
-    per_page?: number;
-  }): Promise<SummaryActivity[]> {
-    const query = new URLSearchParams();
-    if (params?.before != null) query.set("before", String(params.before));
-    if (params?.after != null) query.set("after", String(params.after));
-    if (params?.page != null) query.set("page", String(params.page));
-    if (params?.per_page != null) query.set("per_page", String(params.per_page));
-
-    const qs = query.toString();
-    return this.get<SummaryActivity[]>(
-      `/athlete/activities${qs ? `?${qs}` : ""}`,
-    );
-  }
-
-  /**
-   * List ALL activities for the authenticated athlete, automatically
-   * paginating through all pages.
-   *
-   * @param params.after - Only return activities after this Unix epoch timestamp
-   * @param params.before - Only return activities before this Unix epoch timestamp
-   * @param params.per_page - Items per page (defaults to 200)
-   */
-  async listAllActivities(params?: {
-    after?: number;
-    before?: number;
-    per_page?: number;
-  }): Promise<SummaryActivity[]> {
-    const perPage = params?.per_page ?? 200;
-    const all: SummaryActivity[] = [];
-    let page = 1;
-
-    while (true) {
-      const batch = await this.listActivities({
-        after: params?.after,
-        before: params?.before,
-        page,
-        per_page: perPage,
-      });
-      all.push(...batch);
-      if (batch.length < perPage) break;
-      page++;
-    }
-
-    return all;
-  }
-
-  /**
-   * Get a detailed activity by ID.
-   *
-   * Strava API: `GET /activities/{id}`
-   */
-  async getActivity(id: number): Promise<DetailedActivity> {
-    return this.get<DetailedActivity>(`/activities/${id}`);
-  }
-
-  /**
-   * Get time-series streams for an activity.
-   *
-   * Strava API: `GET /activities/{id}/streams`
-   *
-   * @param id - Activity ID
-   * @param keys - Stream types to request (e.g. `["heartrate", "watts", "latlng", "altitude", "time"]`)
-   */
-  async getActivityStreams(
-    id: number,
-    keys: string[] = [
-      "time",
-      "heartrate",
-      "watts",
-      "cadence",
-      "latlng",
-      "altitude",
-      "velocity_smooth",
-      "grade_smooth",
-      "distance",
-      "temp",
-    ],
-  ): Promise<StreamSet> {
-    const query = new URLSearchParams({
-      keys: keys.join(","),
-      key_by_type: "true",
-    });
-    const streams = await this.get<Record<string, Stream>>(
-      `/activities/${id}/streams?${query.toString()}`,
-    );
-    return streams as StreamSet;
-  }
-
-  /**
-   * Get laps for an activity.
-   *
-   * Strava API: `GET /activities/{id}/laps`
-   */
-  async getActivityLaps(id: number): Promise<Lap[]> {
-    return this.get<Lap[]>(`/activities/${id}/laps`);
-  }
-
-  // ─── Internal ────────────────────────────────────────────────────────────
-
-  private async get<T>(path: string): Promise<T> {
-    const url = `${this.baseUrl}${API_PREFIX}${path}`;
-    const response = await fetch(url, {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${this.accessToken}`,
-        Accept: "application/json",
-      },
-    });
-
-    if (!response.ok) {
-      const body = await response.text().catch(() => "");
-      throw new StravaApiError(
-        `Strava API error: ${response.status} ${response.statusText}`,
-        response.status,
-        body,
-      );
-    }
-
-    return (await response.json()) as T;
-  }
-}
-
-// ─── Error ───────────────────────────────────────────────────────────────────
-
-export class StravaApiError extends Error {
-  constructor(
-    message: string,
-    public readonly status: number,
-    public readonly body: string,
-  ) {
-    super(message);
-    this.name = "StravaApiError";
-  }
-}

package/src/strava/index.ts

@@ -1,54 +0,0 @@
-// ─── @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

@@ -1,69 +0,0 @@
-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/sync.ts

@@ -1,168 +0,0 @@
-// ─── 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 });
-}