@nativesquare/soma 0.1.2 → 0.2.0

package/src/strava/athlete.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+import { transformAthlete } from "./athlete.js";
+import type { DetailedAthlete } from "./types.js";
+
+const baseAthlete: DetailedAthlete = {
+  id: 10001,
+  username: "carlos_v",
+  resource_state: 3,
+  firstname: "Carlos",
+  lastname: "Velasquez",
+  city: "Boulder",
+  state: "Colorado",
+  country: "US",
+  sex: "M",
+  premium: true,
+  summit: true,
+  created_at: "2019-03-12T08:15:00Z",
+  updated_at: "2025-12-01T14:22:30Z",
+  badge_type_id: 6,
+  profile_medium:
+    "https://dgalywyr863hv.cloudfront.net/pictures/athletes/10001/10001/2/medium.jpg",
+  profile:
+    "https://dgalywyr863hv.cloudfront.net/pictures/athletes/10001/10001/2/large.jpg",
+  friend: null,
+  follower: null,
+  follower_count: 342,
+  friend_count: 128,
+  mutual_friend_count: 0,
+  athlete_type: 0,
+  date_preference: "%m/%d/%Y",
+  measurement_preference: "feet",
+  ftp: 310,
+  weight: 72.5,
+  clubs: [
+    {
+      id: 5001,
+      resource_state: 2,
+      name: "Boulder Cycling Club",
+      profile_medium:
+        "https://dgalywyr863hv.cloudfront.net/pictures/clubs/5001/medium.jpg",
+      sport_type: "cycling",
+      city: "Boulder",
+      state: "Colorado",
+      country: "US",
+      member_count: 215,
+      featured: false,
+      verified: true,
+      url: "boulder-cycling-club",
+    },
+  ],
+  bikes: [
+    {
+      id: "b1000001",
+      primary: true,
+      name: "Specialized Tarmac SL7",
+      resource_state: 2,
+      distance: 12450600,
+    },
+    {
+      id: "b1000002",
+      primary: false,
+      name: "Canyon Endurace CF",
+      resource_state: 2,
+      distance: 5820300,
+    },
+  ],
+  shoes: [
+    {
+      id: "g1000001",
+      primary: true,
+      name: "Shimano S-Phyre RC9",
+      resource_state: 2,
+      distance: 8200000,
+    },
+  ],
+};
+
+describe("transformAthlete", () => {
+  it("maps first and last name", () => {
+    const result = transformAthlete(baseAthlete);
+    expect(result.first_name).toBe("Carlos");
+    expect(result.last_name).toBe("Velasquez");
+  });
+
+  it("maps location fields", () => {
+    const result = transformAthlete(baseAthlete);
+    expect(result.city).toBe("Boulder");
+    expect(result.state).toBe("Colorado");
+    expect(result.country).toBe("US");
+  });
+
+  it("maps sex M to male", () => {
+    const result = transformAthlete(baseAthlete);
+    expect(result.sex).toBe("male");
+  });
+
+  it("maps sex F to female", () => {
+    const female = { ...baseAthlete, sex: "F" as const };
+    const result = transformAthlete(female);
+    expect(result.sex).toBe("female");
+  });
+
+  it("maps null sex to undefined", () => {
+    const noSex = { ...baseAthlete, sex: null };
+    const result = transformAthlete(noSex);
+    expect(result.sex).toBeUndefined();
+  });
+
+  it("maps created_at to joined_provider", () => {
+    const result = transformAthlete(baseAthlete);
+    expect(result.joined_provider).toBe("2019-03-12T08:15:00Z");
+  });
+
+  it("maps bikes and shoes to devices", () => {
+    const result = transformAthlete(baseAthlete);
+    expect(result.devices).toHaveLength(3);
+    expect(result.devices?.[0]).toEqual({
+      name: "Specialized Tarmac SL7",
+      id: "b1000001",
+    });
+    expect(result.devices?.[2]).toEqual({
+      name: "Shimano S-Phyre RC9",
+      id: "g1000001",
+    });
+  });
+
+  it("handles athlete with null location", () => {
+    const noLocation = {
+      ...baseAthlete,
+      city: null,
+      state: null,
+      country: null,
+    };
+    const result = transformAthlete(noLocation);
+    expect(result.city).toBeUndefined();
+    expect(result.state).toBeUndefined();
+    expect(result.country).toBeUndefined();
+  });
+});

package/src/strava/athlete.ts

@@ -0,0 +1,47 @@
+// ─── Athlete Transformer ─────────────────────────────────────────────────────
+// Transforms a Strava DetailedAthlete into the Soma Athlete schema shape.
+
+import type { DetailedAthlete } from "./types.js";
+
+/**
+ * The output shape of {@link transformAthlete}.
+ */
+export type AthleteData = ReturnType<typeof transformAthlete>;
+
+/**
+ * Transform a Strava athlete profile into a Soma Athlete document shape.
+ *
+ * Strava provides a relatively rich profile compared to HealthKit, including
+ * name, location, sex, and the date the athlete joined Strava.
+ *
+ * @param athlete - The Strava DetailedAthlete from `GET /athlete`
+ * @returns Soma Athlete fields (without connectionId/userId)
+ *
+ * @example
+ * ```ts
+ * const data = transformAthlete(stravaAthlete);
+ * await soma.ingestAthlete(ctx, { connectionId, userId, ...data });
+ * ```
+ */
+export function transformAthlete(athlete: DetailedAthlete) {
+  const sexMap: Record<string, string> = {
+    M: "male",
+    F: "female",
+  };
+
+  return {
+    first_name: athlete.firstname ?? undefined,
+    last_name: athlete.lastname ?? undefined,
+    city: athlete.city ?? undefined,
+    state: athlete.state ?? undefined,
+    country: athlete.country ?? undefined,
+    sex: athlete.sex ? sexMap[athlete.sex] : undefined,
+    joined_provider: athlete.created_at ?? undefined,
+    devices: athlete.bikes && athlete.shoes
+      ? [
+        ...athlete.bikes.map((b) => ({ name: b.name, id: b.id })),
+        ...athlete.shoes.map((s) => ({ name: s.name, id: s.id })),
+      ]
+      : undefined,
+  };
+}

package/src/strava/auth.test.ts

@@ -0,0 +1,78 @@
+import { describe, expect, it } from "vitest";
+import { buildAuthUrl } from "./auth.js";
+
+describe("buildAuthUrl", () => {
+  it("builds a valid Strava authorization URL", () => {
+    const url = buildAuthUrl({
+      clientId: "12345",
+      redirectUri: "https://example.com/callback",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.origin).toBe("https://www.strava.com");
+    expect(parsed.pathname).toBe("/oauth/authorize");
+    expect(parsed.searchParams.get("client_id")).toBe("12345");
+    expect(parsed.searchParams.get("redirect_uri")).toBe(
+      "https://example.com/callback",
+    );
+    expect(parsed.searchParams.get("response_type")).toBe("code");
+    expect(parsed.searchParams.get("approval_prompt")).toBe("auto");
+    expect(parsed.searchParams.get("scope")).toBe(
+      "read,activity:read_all,profile:read_all",
+    );
+  });
+
+  it("uses custom scope", () => {
+    const url = buildAuthUrl({
+      clientId: "12345",
+      redirectUri: "https://example.com/callback",
+      scope: "read,activity:read",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get("scope")).toBe("read,activity:read");
+  });
+
+  it("includes state parameter when provided", () => {
+    const url = buildAuthUrl({
+      clientId: "12345",
+      redirectUri: "https://example.com/callback",
+      state: "csrf-token-123",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get("state")).toBe("csrf-token-123");
+  });
+
+  it("omits state parameter when not provided", () => {
+    const url = buildAuthUrl({
+      clientId: "12345",
+      redirectUri: "https://example.com/callback",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.searchParams.has("state")).toBe(false);
+  });
+
+  it("uses custom baseUrl", () => {
+    const url = buildAuthUrl({
+      clientId: "12345",
+      redirectUri: "https://example.com/callback",
+      baseUrl: "https://strava-mock-server.onrender.com",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.origin).toBe("https://strava-mock-server.onrender.com");
+  });
+
+  it("strips trailing slashes from baseUrl", () => {
+    const url = buildAuthUrl({
+      clientId: "12345",
+      redirectUri: "https://example.com/callback",
+      baseUrl: "https://mock.example.com///",
+    });
+
+    expect(url).toMatch(/^https:\/\/mock\.example\.com\/oauth/);
+    expect(url).not.toMatch(/\/\/oauth/);
+  });
+});

package/src/strava/auth.ts

@@ -0,0 +1,185 @@
+// ─── Strava OAuth Helpers ────────────────────────────────────────────────────
+// Pure helper functions for the Strava OAuth 2.0 Authorization Code flow.
+// No external dependencies — uses the global `fetch`.
+
+import type { OAuthTokenResponse } from "./types.js";
+
+const DEFAULT_BASE_URL = "https://www.strava.com";
+
+// ─── Build Authorization URL ─────────────────────────────────────────────────
+
+export interface BuildAuthUrlOptions {
+  /** Your Strava application's Client ID. */
+  clientId: string;
+  /** The URL Strava will redirect to after authorization. */
+  redirectUri: string;
+  /**
+   * Comma-separated Strava OAuth scopes.
+   * @default "read,activity:read_all,profile:read_all"
+   */
+  scope?: string;
+  /** Optional state parameter for CSRF protection. */
+  state?: string;
+  /**
+   * Base URL of the Strava site.
+   * @default "https://www.strava.com"
+   */
+  baseUrl?: string;
+}
+
+/**
+ * Build the Strava OAuth authorization URL.
+ *
+ * Redirect the user to this URL to begin the OAuth flow. After the user
+ * grants access, Strava will redirect back to `redirectUri` with a `code`
+ * query parameter.
+ *
+ * @example
+ * ```ts
+ * const url = buildAuthUrl({
+ *   clientId: process.env.STRAVA_CLIENT_ID!,
+ *   redirectUri: "https://your-app.com/api/strava/callback",
+ * });
+ * // Redirect user to `url`
+ * ```
+ */
+export function buildAuthUrl(opts: BuildAuthUrlOptions): string {
+  const base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const params = new URLSearchParams({
+    client_id: opts.clientId,
+    redirect_uri: opts.redirectUri,
+    response_type: "code",
+    approval_prompt: "auto",
+    scope: opts.scope ?? "read,activity:read_all,profile:read_all",
+  });
+
+  if (opts.state) {
+    params.set("state", opts.state);
+  }
+
+  return `${base}/oauth/authorize?${params.toString()}`;
+}
+
+// ─── Exchange Authorization Code ─────────────────────────────────────────────
+
+export interface ExchangeCodeOptions {
+  /** Your Strava application's Client ID. */
+  clientId: string;
+  /** Your Strava application's Client Secret. */
+  clientSecret: string;
+  /** The authorization code from the OAuth callback. */
+  code: string;
+  /**
+   * Base URL of the Strava site.
+   * @default "https://www.strava.com"
+   */
+  baseUrl?: string;
+}
+
+/**
+ * Exchange an authorization code for access and refresh tokens.
+ *
+ * Call this from your OAuth callback endpoint after receiving the `code`
+ * query parameter from Strava.
+ *
+ * @returns The token response including `access_token`, `refresh_token`,
+ *          `expires_at`, and the authenticated `athlete` profile.
+ *
+ * @example
+ * ```ts
+ * const tokens = await exchangeCode({
+ *   clientId: process.env.STRAVA_CLIENT_ID!,
+ *   clientSecret: process.env.STRAVA_CLIENT_SECRET!,
+ *   code: request.query.code,
+ * });
+ * // Store tokens.access_token, tokens.refresh_token, tokens.expires_at
+ * ```
+ */
+export async function exchangeCode(
+  opts: ExchangeCodeOptions,
+): Promise<OAuthTokenResponse> {
+  const base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const url = `${base}/oauth/token`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_id: opts.clientId,
+      client_secret: opts.clientSecret,
+      code: opts.code,
+      grant_type: "authorization_code",
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `Strava OAuth error (exchangeCode): ${response.status} ${response.statusText} — ${body}`,
+    );
+  }
+
+  return (await response.json()) as OAuthTokenResponse;
+}
+
+// ─── Refresh Token ───────────────────────────────────────────────────────────
+
+export interface RefreshTokenOptions {
+  /** Your Strava application's Client ID. */
+  clientId: string;
+  /** Your Strava application's Client Secret. */
+  clientSecret: string;
+  /** The refresh token from a previous token exchange or refresh. */
+  refreshToken: string;
+  /**
+   * Base URL of the Strava site.
+   * @default "https://www.strava.com"
+   */
+  baseUrl?: string;
+}
+
+/**
+ * Refresh an expired access token using a refresh token.
+ *
+ * Strava access tokens expire after ~6 hours. Call this when the
+ * `expires_at` timestamp has passed to obtain a fresh access token.
+ *
+ * @returns A new token response with a fresh `access_token` and
+ *          possibly a new `refresh_token`.
+ *
+ * @example
+ * ```ts
+ * const tokens = await refreshToken({
+ *   clientId: process.env.STRAVA_CLIENT_ID!,
+ *   clientSecret: process.env.STRAVA_CLIENT_SECRET!,
+ *   refreshToken: storedRefreshToken,
+ * });
+ * // Update stored tokens
+ * ```
+ */
+export async function refreshToken(
+  opts: RefreshTokenOptions,
+): Promise<OAuthTokenResponse> {
+  const base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const url = `${base}/oauth/token`;
+
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_id: opts.clientId,
+      client_secret: opts.clientSecret,
+      refresh_token: opts.refreshToken,
+      grant_type: "refresh_token",
+    }),
+  });
+
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw new Error(
+      `Strava OAuth error (refreshToken): ${response.status} ${response.statusText} — ${body}`,
+    );
+  }
+
+  return (await response.json()) as OAuthTokenResponse;
+}

package/src/strava/client.ts

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