@clipin/convex-wearables 0.0.2 → 0.0.3

package/src/component/providers/oauth.test.ts

@@ -0,0 +1,174 @@
+/**
+ * Tests for OAuth utility pure functions.
+ *
+ * No network calls — tests URL building, PKCE generation, and config handling.
+ */
+
+import { describe, expect, it } from "vitest";
+import { buildAuthorizationUrl, generateCodeChallenge, generateRandomString } from "./oauth";
+import type { OAuthProviderConfig } from "./types";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeConfig(overrides: Partial<OAuthProviderConfig> = {}): OAuthProviderConfig {
+  return {
+    endpoints: {
+      authorizeUrl: "https://provider.example.com/oauth/authorize",
+      tokenUrl: "https://provider.example.com/oauth/token",
+      apiBaseUrl: "https://api.provider.example.com",
+    },
+    clientId: "test-client-id",
+    clientSecret: "test-client-secret",
+    defaultScope: "read write",
+    usePkce: false,
+    authMethod: "body",
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("generateRandomString", () => {
+  it("generates a string of the requested length", () => {
+    const s = generateRandomString(32);
+    expect(s).toHaveLength(32);
+  });
+
+  it("generates different strings each time", () => {
+    const a = generateRandomString(32);
+    const b = generateRandomString(32);
+    expect(a).not.toBe(b);
+  });
+
+  it("only contains URL-safe characters", () => {
+    const s = generateRandomString(100);
+    expect(s).toMatch(/^[A-Za-z0-9\-._~]+$/);
+  });
+});
+
+describe("generateCodeChallenge", () => {
+  it("produces a base64url-encoded string", async () => {
+    const challenge = await generateCodeChallenge("test-verifier");
+    // Base64url: no +, /, or = padding
+    expect(challenge).not.toMatch(/[+/=]/);
+    expect(challenge.length).toBeGreaterThan(0);
+  });
+
+  it("produces consistent output for same input", async () => {
+    const a = await generateCodeChallenge("same-verifier");
+    const b = await generateCodeChallenge("same-verifier");
+    expect(a).toBe(b);
+  });
+
+  it("produces different output for different input", async () => {
+    const a = await generateCodeChallenge("verifier-1");
+    const b = await generateCodeChallenge("verifier-2");
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("buildAuthorizationUrl", () => {
+  it("builds a basic authorization URL with required params", () => {
+    const config = makeConfig();
+    const url = buildAuthorizationUrl({
+      config,
+      redirectUri: "https://myapp.com/callback",
+      state: "random-state-123",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.origin).toBe("https://provider.example.com");
+    expect(parsed.pathname).toBe("/oauth/authorize");
+    expect(parsed.searchParams.get("client_id")).toBe("test-client-id");
+    expect(parsed.searchParams.get("redirect_uri")).toBe("https://myapp.com/callback");
+    expect(parsed.searchParams.get("response_type")).toBe("code");
+    expect(parsed.searchParams.get("scope")).toBe("read write");
+    expect(parsed.searchParams.get("state")).toBe("random-state-123");
+  });
+
+  it("includes PKCE code_challenge when enabled", () => {
+    const config = makeConfig({ usePkce: true });
+    const url = buildAuthorizationUrl({
+      config,
+      redirectUri: "https://myapp.com/callback",
+      state: "state-abc",
+      codeChallenge: "challenge-xyz",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get("code_challenge")).toBe("challenge-xyz");
+    expect(parsed.searchParams.get("code_challenge_method")).toBe("S256");
+  });
+
+  it("omits PKCE params when not enabled", () => {
+    const config = makeConfig({ usePkce: false });
+    const url = buildAuthorizationUrl({
+      config,
+      redirectUri: "https://myapp.com/callback",
+      state: "state-abc",
+      codeChallenge: "challenge-xyz",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get("code_challenge")).toBeNull();
+    expect(parsed.searchParams.get("code_challenge_method")).toBeNull();
+  });
+
+  it("includes extra authorize params", () => {
+    const config = makeConfig({
+      extraAuthorizeParams: {
+        "Ocp-Apim-Subscription-Key": "suunto-key-123",
+        prompt: "consent",
+      },
+    });
+
+    const url = buildAuthorizationUrl({
+      config,
+      redirectUri: "https://myapp.com/callback",
+      state: "state-abc",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get("Ocp-Apim-Subscription-Key")).toBe("suunto-key-123");
+    expect(parsed.searchParams.get("prompt")).toBe("consent");
+  });
+});
+
+describe("provider-specific OAuth configs", () => {
+  it("Strava config has correct endpoints", async () => {
+    const { stravaOAuthConfig } = await import("./strava");
+    const config = stravaOAuthConfig({
+      clientId: "my-client-id",
+      clientSecret: "my-secret",
+    });
+
+    expect(config.endpoints.authorizeUrl).toBe("https://www.strava.com/oauth/authorize");
+    expect(config.endpoints.tokenUrl).toBe("https://www.strava.com/api/v3/oauth/token");
+    expect(config.clientId).toBe("my-client-id");
+    expect(config.clientSecret).toBe("my-secret");
+    expect(config.usePkce).toBe(false);
+    expect(config.authMethod).toBe("body");
+    expect(config.defaultScope).toContain("activity:read_all");
+  });
+
+  it("Strava auth URL includes correct scope", async () => {
+    const { stravaOAuthConfig } = await import("./strava");
+    const config = stravaOAuthConfig({
+      clientId: "cid",
+      clientSecret: "csec",
+    });
+
+    const url = buildAuthorizationUrl({
+      config,
+      redirectUri: "https://app.com/cb",
+      state: "st",
+    });
+
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get("scope")).toBe("activity:read_all,profile:read_all");
+  });
+});

package/src/component/providers/oauth.ts

@@ -0,0 +1,246 @@
+/**
+ * Generic OAuth 2.0 utilities.
+ * Used by provider-specific OAuth configs to build authorization URLs,
+ * exchange codes for tokens, and refresh tokens.
+ */
+
+import type { OAuthProviderConfig, OAuthTokenResponse } from "./types";
+
+// ---------------------------------------------------------------------------
+// PKCE helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a random URL-safe string for use as state or code_verifier.
+ */
+export function generateRandomString(length: number): string {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
+  const array = new Uint8Array(length);
+  crypto.getRandomValues(array);
+  return Array.from(array, (b) => chars[b % chars.length]).join("");
+}
+
+/**
+ * Generate a PKCE code_challenge from a code_verifier using SHA-256.
+ */
+export async function generateCodeChallenge(codeVerifier: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const data = encoder.encode(codeVerifier);
+  const digest = await crypto.subtle.digest("SHA-256", data);
+  // Base64url encode (no padding)
+  const base64 = btoa(String.fromCharCode(...new Uint8Array(digest)));
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// ---------------------------------------------------------------------------
+// Authorization URL
+// ---------------------------------------------------------------------------
+
+export interface AuthUrlParams {
+  config: OAuthProviderConfig;
+  redirectUri: string;
+  state: string;
+  codeChallenge?: string;
+}
+
+/**
+ * Build the provider's authorization URL.
+ */
+export function buildAuthorizationUrl(params: AuthUrlParams): string {
+  const { config, redirectUri, state, codeChallenge } = params;
+  const url = new URL(config.endpoints.authorizeUrl);
+
+  url.searchParams.set("client_id", config.clientId);
+  url.searchParams.set("redirect_uri", redirectUri);
+  url.searchParams.set("response_type", "code");
+  if (config.defaultScope) {
+    url.searchParams.set("scope", config.defaultScope);
+  }
+  url.searchParams.set("state", state);
+
+  if (config.usePkce && codeChallenge) {
+    url.searchParams.set("code_challenge", codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+  }
+
+  // Extra params (e.g., Suunto subscription key)
+  if (config.extraAuthorizeParams) {
+    for (const [key, value] of Object.entries(config.extraAuthorizeParams)) {
+      url.searchParams.set(key, value);
+    }
+  }
+
+  return url.toString();
+}
+
+// ---------------------------------------------------------------------------
+// Token Exchange
+// ---------------------------------------------------------------------------
+
+/**
+ * Exchange an authorization code for tokens.
+ */
+export async function exchangeCodeForTokens(
+  config: OAuthProviderConfig,
+  code: string,
+  redirectUri: string,
+  codeVerifier?: string,
+): Promise<OAuthTokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+  });
+
+  if (config.usePkce && codeVerifier) {
+    body.set("code_verifier", codeVerifier);
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/x-www-form-urlencoded",
+    Accept: "application/json",
+  };
+
+  if (config.authMethod === "basic") {
+    const credentials = btoa(`${config.clientId}:${config.clientSecret}`);
+    headers.Authorization = `Basic ${credentials}`;
+  } else {
+    // Body-based auth
+    body.set("client_id", config.clientId);
+    body.set("client_secret", config.clientSecret);
+  }
+
+  const response = await fetch(config.endpoints.tokenUrl, {
+    method: "POST",
+    headers,
+    body: body.toString(),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Token exchange failed (${response.status}): ${text}`);
+  }
+
+  return (await response.json()) as OAuthTokenResponse;
+}
+
+// ---------------------------------------------------------------------------
+// Token Refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * Refresh an expired access token.
+ */
+export async function refreshAccessToken(
+  config: OAuthProviderConfig,
+  refreshToken: string,
+): Promise<OAuthTokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+  });
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/x-www-form-urlencoded",
+    Accept: "application/json",
+  };
+
+  if (config.authMethod === "basic") {
+    const credentials = btoa(`${config.clientId}:${config.clientSecret}`);
+    headers.Authorization = `Basic ${credentials}`;
+  } else {
+    body.set("client_id", config.clientId);
+    body.set("client_secret", config.clientSecret);
+  }
+
+  const response = await fetch(config.endpoints.tokenUrl, {
+    method: "POST",
+    headers,
+    body: body.toString(),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`Token refresh failed (${response.status}): ${text}`);
+  }
+
+  return (await response.json()) as OAuthTokenResponse;
+}
+
+// ---------------------------------------------------------------------------
+// Authenticated API requests (with retry)
+// ---------------------------------------------------------------------------
+
+const MAX_RETRIES = 3;
+const RETRY_BASE_DELAY_MS = 15_000;
+
+/**
+ * Make an authenticated request to a provider API with automatic retry on 429.
+ */
+export async function makeAuthenticatedRequest<T = unknown>(
+  baseUrl: string,
+  endpoint: string,
+  accessToken: string,
+  options: {
+    method?: string;
+    params?: Record<string, string | number>;
+    body?: unknown;
+    headers?: Record<string, string>;
+  } = {},
+): Promise<T> {
+  const { method = "GET", params, body, headers: extraHeaders } = options;
+
+  const url = new URL(endpoint, baseUrl);
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      url.searchParams.set(key, String(value));
+    }
+  }
+
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${accessToken}`,
+    Accept: "application/json",
+    ...extraHeaders,
+  };
+
+  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+    const response = await fetch(url.toString(), {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    if (response.status === 429 && attempt < MAX_RETRIES) {
+      const delay = RETRY_BASE_DELAY_MS * 2 ** attempt;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      continue;
+    }
+
+    if (response.status === 401) {
+      throw new Error("Authorization expired — token refresh needed");
+    }
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`API request failed (${response.status}): ${text}`);
+    }
+
+    if (response.status === 204) {
+      return undefined as T;
+    }
+
+    const text = await response.text();
+    if (!text) {
+      return undefined as T;
+    }
+
+    const contentType = response.headers.get("content-type") ?? "";
+    if (contentType.includes("application/json")) {
+      return JSON.parse(text) as T;
+    }
+
+    return text as T;
+  }
+
+  throw new Error(`API request failed after ${MAX_RETRIES} retries (rate limited)`);
+}

package/src/component/providers/polar.ts

@@ -0,0 +1,220 @@
+/**
+ * Polar provider adapter — OAuth 2.0 + workout pull flow.
+ */
+
+import { makeAuthenticatedRequest } from "./oauth";
+import type {
+  NormalizedEvent,
+  OAuthProviderConfig,
+  ProviderAdapter,
+  ProviderCredentials,
+} from "./types";
+
+const POLAR_API_BASE = "https://www.polaraccesslink.com";
+const POLAR_AUTHORIZE_URL = "https://flow.polar.com/oauth2/authorization";
+const POLAR_TOKEN_URL = "https://polarremote.com/v2/oauth2/token";
+const POLAR_WORKOUT_SCOPE = "accesslink.read_all";
+
+const POLAR_WORKOUT_TYPE_MAPPINGS: Array<[string, string | null, string]> = [
+  ["RUNNING", null, "running"],
+  ["RUNNING", "RUNNING_ROAD", "running"],
+  ["RUNNING", "RUNNING_TRAIL", "trail_running"],
+  ["RUNNING", "RUNNING_TREADMILL", "treadmill"],
+  ["CYCLING", null, "cycling"],
+  ["CYCLING", "CYCLING_ROAD", "cycling"],
+  ["CYCLING", "CYCLING_MOUNTAIN", "mountain_biking"],
+  ["CYCLING", "CYCLING_INDOOR", "indoor_cycling"],
+  ["OTHER", "CYCLING_MOUNTAIN_BIKE", "mountain_biking"],
+  ["OTHER", "CYCLING_CYCLOCROSS", "cyclocross"],
+  ["SWIMMING", null, "swimming"],
+  ["SWIMMING", "SWIMMING_POOL", "pool_swimming"],
+  ["SWIMMING", "SWIMMING_OPEN_WATER", "open_water_swimming"],
+  ["OTHER", "AQUATICS_SWIMMING", "swimming"],
+  ["WALKING", null, "walking"],
+  ["OTHER", "WALKING", "walking"],
+  ["OTHER", "WALKING_NORDIC", "walking"],
+  ["OTHER", "HIKING", "hiking"],
+  ["OTHER", "MOUNTAINEERING", "mountaineering"],
+  ["OTHER", "WINTERSPORTS_CROSS_COUNTRY_SKIING", "cross_country_skiing"],
+  ["OTHER", "WINTERSPORTS_ALPINE_SKIING", "alpine_skiing"],
+  ["OTHER", "WINTERSPORTS_BACKCOUNTRY_SKIING", "backcountry_skiing"],
+  ["OTHER", "WINTERSPORTS_DOWNHILL_SKIING", "alpine_skiing"],
+  ["OTHER", "WINTERSPORTS_SNOWBOARDING", "snowboarding"],
+  ["OTHER", "WINTERSPORTS_SNOWSHOEING", "snowshoeing"],
+  ["OTHER", "WINTERSPORTS_ICE_SKATING", "ice_skating"],
+  ["STRENGTH_TRAINING", null, "strength_training"],
+  ["OTHER", "FITNESS_CARDIO", "cardio_training"],
+  ["OTHER", "FITNESS_ELLIPTICAL", "elliptical"],
+  ["OTHER", "FITNESS_INDOOR_ROWING", "rowing"],
+  ["OTHER", "FITNESS_STAIR_CLIMBING", "stair_climbing"],
+  ["OTHER", "WATERSPORTS_ROWING", "rowing"],
+  ["OTHER", "WATERSPORTS_KAYAKING", "kayaking"],
+  ["OTHER", "WATERSPORTS_CANOEING", "canoeing"],
+  ["OTHER", "WATERSPORTS_STAND_UP_PADDLING", "stand_up_paddleboarding"],
+  ["OTHER", "WATERSPORTS_SURFING", "surfing"],
+  ["OTHER", "WATERSPORTS_KITESURFING", "kitesurfing"],
+  ["OTHER", "WATERSPORTS_WINDSURFING", "windsurfing"],
+  ["OTHER", "WATERSPORTS_SAILING", "sailing"],
+  ["OTHER", "WATERSPORTS_WATERSKI", "other"],
+  ["BASKETBALL", null, "basketball"],
+  ["SOCCER", null, "soccer"],
+  ["OTHER", "TEAMSPORTS_SOCCER", "soccer"],
+  ["OTHER", "TEAMSPORTS_FOOTBALL", "football"],
+  ["OTHER", "TEAMSPORTS_AMERICAN_FOOTBALL", "american_football"],
+  ["OTHER", "TEAMSPORTS_BASEBALL", "baseball"],
+  ["OTHER", "TEAMSPORTS_BASKETBALL", "basketball"],
+  ["OTHER", "TEAMSPORTS_VOLLEYBALL", "volleyball"],
+  ["OTHER", "TEAMSPORTS_HANDBALL", "handball"],
+  ["OTHER", "TEAMSPORTS_RUGBY", "rugby"],
+  ["OTHER", "TEAMSPORTS_HOCKEY", "hockey"],
+  ["OTHER", "TEAMSPORTS_FLOORBALL", "floorball"],
+  ["TENNIS", null, "tennis"],
+  ["OTHER", "RACKET_SPORTS_TENNIS", "tennis"],
+  ["OTHER", "RACKET_SPORTS_BADMINTON", "badminton"],
+  ["OTHER", "RACKET_SPORTS_SQUASH", "squash"],
+  ["OTHER", "RACKET_SPORTS_TABLE_TENNIS", "table_tennis"],
+  ["OTHER", "RACKET_SPORTS_PADEL", "padel"],
+  ["OTHER", "RACKET_SPORTS_PICKLEBALL", "pickleball"],
+  ["OTHER", "COMBAT_SPORTS_BOXING", "boxing"],
+  ["OTHER", "COMBAT_SPORTS_MARTIAL_ARTS", "martial_arts"],
+  ["OTHER", "OUTDOOR_CLIMBING", "rock_climbing"],
+  ["OTHER", "INDOOR_CLIMBING", "rock_climbing"],
+  ["OTHER", "SPORTS_GOLF", "golf"],
+  ["MOTORSPORTS", null, "motorcycling"],
+  ["OTHER", "MOTORSPORTS", "motorcycling"],
+  ["OTHER", "DANCE", "dance"],
+  ["OTHER", "AEROBICS", "aerobics"],
+  ["OTHER", null, "other"],
+];
+
+type PolarExercise = {
+  id: string;
+  device?: string;
+  sport: string;
+  detailed_sport_info?: string | null;
+  start_time: string;
+  start_time_utc_offset: number;
+  duration: string;
+  calories?: number | null;
+  distance?: number | null;
+  heart_rate?: {
+    average?: number | null;
+    maximum?: number | null;
+  };
+};
+
+function resolvePolarWorkoutType(sport: string, detailed?: string | null): string {
+  if (detailed) {
+    const match = POLAR_WORKOUT_TYPE_MAPPINGS.find(
+      ([s, detail]) => s === sport && detail === detailed,
+    );
+    if (match) {
+      return match[2];
+    }
+  }
+  const fallback = POLAR_WORKOUT_TYPE_MAPPINGS.find(
+    ([s, detail]) => s === sport && detail === null,
+  );
+  if (fallback) {
+    return fallback[2];
+  }
+  return "other";
+}
+
+function parsePolarDuration(duration: string): number {
+  const regex = /PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?/;
+  const match = regex.exec(duration);
+  if (!match) return 0;
+  const [, hours = "0", minutes = "0", seconds = "0"] = match;
+  return Number(hours) * 3600 + Number(minutes) * 60 + Number(seconds);
+}
+
+function normalizePolarExercise(exercise: PolarExercise): NormalizedEvent {
+  const durationSeconds = parsePolarDuration(exercise.duration);
+  const baseStart = Date.parse(exercise.start_time);
+  const offsetMs = exercise.start_time_utc_offset * 60_000;
+  const startDatetime = baseStart + offsetMs;
+  const endDatetime = startDatetime + durationSeconds * 1000;
+
+  const heartRateAvg = exercise.heart_rate?.average ?? undefined;
+  const heartRateMax = exercise.heart_rate?.maximum ?? undefined;
+
+  return {
+    category: "workout",
+    type: resolvePolarWorkoutType(exercise.sport, exercise.detailed_sport_info),
+    sourceName: exercise.device ?? "Polar",
+    deviceModel: exercise.device,
+    durationSeconds: durationSeconds || undefined,
+    startDatetime,
+    endDatetime,
+    externalId: `polar-${exercise.id}`,
+    heartRateAvg,
+    heartRateMax,
+    energyBurned: exercise.calories ?? undefined,
+    distance: exercise.distance ?? undefined,
+  };
+}
+
+function buildPolarOAuthConfig(credentials: ProviderCredentials): OAuthProviderConfig {
+  return {
+    endpoints: {
+      authorizeUrl: POLAR_AUTHORIZE_URL,
+      tokenUrl: POLAR_TOKEN_URL,
+      apiBaseUrl: POLAR_API_BASE,
+    },
+    clientId: credentials.clientId,
+    clientSecret: credentials.clientSecret,
+    defaultScope: POLAR_WORKOUT_SCOPE,
+    usePkce: false,
+    authMethod: "basic",
+  };
+}
+
+async function registerMember(accessToken: string, appUserId: string): Promise<void> {
+  try {
+    await fetch(`${POLAR_API_BASE}/v3/users`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+      },
+      body: JSON.stringify({ "member-id": appUserId }),
+    });
+  } catch (error) {
+    console.warn("Polar member registration failed", error);
+  }
+}
+
+async function fetchPolarWorkouts(
+  accessToken: string,
+  startDate: number,
+  endDate: number,
+  _credentials?: ProviderCredentials,
+): Promise<NormalizedEvent[]> {
+  const exercises = await makeAuthenticatedRequest<PolarExercise[]>(
+    POLAR_API_BASE,
+    "/v3/exercises",
+    accessToken,
+  );
+
+  const records = Array.isArray(exercises) ? exercises : [];
+  return records
+    .map(normalizePolarExercise)
+    .filter((event) => event.startDatetime >= startDate && event.startDatetime <= endDate);
+}
+
+export const polarProvider: ProviderAdapter = {
+  name: "polar",
+  oauthConfig: buildPolarOAuthConfig,
+  getUserInfo: async (_accessToken, tokenResponse) => ({
+    providerUserId: tokenResponse?.x_user_id != null ? String(tokenResponse.x_user_id) : null,
+    username: null,
+  }),
+  postConnect: async (accessToken, _tokenResponse, appUserId) => {
+    if (appUserId) {
+      await registerMember(accessToken, appUserId);
+    }
+  },
+  fetchEvents: fetchPolarWorkouts,
+};

package/src/component/providers/registry.ts

@@ -0,0 +1,37 @@
+/**
+ * Provider registry — maps provider names to their OAuth configs and data fetchers.
+ */
+
+import { garminProvider } from "./garmin";
+import { polarProvider } from "./polar";
+import { stravaProvider } from "./strava";
+import { suuntoProvider } from "./suunto";
+import type { ProviderAdapter } from "./types";
+import { whoopProvider } from "./whoop";
+
+// ---------------------------------------------------------------------------
+// Provider definition
+// ---------------------------------------------------------------------------
+
+const PROVIDERS: Record<string, ProviderAdapter> = {
+  strava: stravaProvider,
+  garmin: garminProvider,
+  polar: polarProvider,
+  whoop: whoopProvider,
+  suunto: suuntoProvider,
+};
+
+/**
+ * Get the provider definition for a given provider name.
+ * Returns undefined if the provider is not yet implemented.
+ */
+export function getProvider(name: string): ProviderAdapter | undefined {
+  return PROVIDERS[name];
+}
+
+/**
+ * Get all implemented provider names.
+ */
+export function getImplementedProviders(): string[] {
+  return Object.keys(PROVIDERS);
+}