@nativesquare/soma 0.9.3 → 0.10.0

package/src/{strava → component/strava}/auth.ts

@@ -1,185 +1,143 @@
-// ─── 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;
-}
+// ─── Strava OAuth 2.0 Helpers ────────────────────────────────────────────────
+// Pure helper functions for the Strava OAuth 2.0 Authorization Code flow.
+// No external dependencies — uses the global `fetch`.
+
+export interface StravaOAuthTokenResponse {
+  token_type: string;
+  expires_at: number; // Unix timestamp
+  expires_in: number; // seconds
+  refresh_token: string;
+  access_token: string;
+  athlete: {
+    id: number;
+    firstname: string;
+    lastname: string;
+  };
+}
+
+// ─── 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;
+  /** State parameter for CSRF protection (echoed back in the callback). */
+  state?: 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.
+ */
+export function buildAuthUrl(opts: BuildAuthUrlOptions): string {
+  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 `https://www.strava.com/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;
+}
+
+/**
+ * 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.
+ */
+export async function exchangeCode(
+  opts: ExchangeCodeOptions,
+): Promise<StravaOAuthTokenResponse> {
+  const response = await fetch("https://www.strava.com/oauth/token", {
+    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 StravaOAuthTokenResponse;
+}
+
+// ─── 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;
+}
+
+/**
+ * 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`.
+ */
+export async function refreshToken(
+  opts: RefreshTokenOptions,
+): Promise<StravaOAuthTokenResponse> {
+  const response = await fetch("https://www.strava.com/oauth/token", {
+    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 StravaOAuthTokenResponse;
+}

package/src/component/strava/client.ts

@@ -0,0 +1,20 @@
+// ─── Strava API Helper ──────────────────────────────────────────────────────
+// Shared utility for calling the Strava API v3.
+// Uses the auto-generated @hey-api/openapi-ts SDK.
+
+import { createClient, createConfig } from "./types/stravaApi/client/index.js";
+
+// ─── Strava API Client ─────────────────────────────────────────────────────
+
+/**
+ * Create a configured Strava API client with Bearer auth.
+ *
+ * Each call creates a lightweight client instance — no connection pooling or
+ * shared state. Safe to create per-request.
+ */
+export function createStravaClient(accessToken: string) {
+  return createClient(createConfig({
+    baseUrl: "https://www.strava.com/api/v3",
+    headers: { Authorization: `Bearer ${accessToken}` },
+  }));
+}

package/src/component/strava/private.ts

@@ -1,89 +1,147 @@
-// ─── Internal Token CRUD ─────────────────────────────────────────────────────
-// These are only callable from within the component (actions in this file).
-
-import { v } from "convex/values";
-import {
-  internalMutation,
-  internalQuery,
-} from "../_generated/server";
-
-/**
- * Store or update OAuth tokens for a connection.
- * Upserts by connectionId — one token record per connection.
- */
-export const storeTokens = internalMutation({
-  args: {
-    connectionId: v.id("connections"),
-    accessToken: v.string(),
-    refreshToken: v.string(),
-    expiresAt: v.number(),
-  },
-  returns: v.null(),
-  handler: async (ctx, args) => {
-    const existing = await ctx.db
-      .query("providerTokens")
-      .withIndex("by_connectionId", (q) =>
-        q.eq("connectionId", args.connectionId),
-      )
-      .first();
-
-    if (existing) {
-      await ctx.db.patch(existing._id, {
-        accessToken: args.accessToken,
-        refreshToken: args.refreshToken,
-        expiresAt: args.expiresAt,
-      });
-      return null;
-    }
-
-    await ctx.db.insert("providerTokens", args);
-    return null;
-  },
-});
-
-/**
- * Get stored tokens for a connection.
- */
-export const getTokens = internalQuery({
-  args: { connectionId: v.id("connections") },
-  returns: v.union(
-    v.object({
-      _id: v.id("providerTokens"),
-      _creationTime: v.number(),
-      connectionId: v.id("connections"),
-      accessToken: v.string(),
-      refreshToken: v.optional(v.string()),
-      expiresAt: v.optional(v.number()),
-    }),
-    v.null(),
-  ),
-  handler: async (ctx, args) => {
-    return await ctx.db
-      .query("providerTokens")
-      .withIndex("by_connectionId", (q) =>
-        q.eq("connectionId", args.connectionId),
-      )
-      .first();
-  },
-});
-
-/**
- * Delete stored tokens for a connection.
- */
-export const deleteTokens = internalMutation({
-  args: { connectionId: v.id("connections") },
-  returns: v.null(),
-  handler: async (ctx, args) => {
-    const existing = await ctx.db
-      .query("providerTokens")
-      .withIndex("by_connectionId", (q) =>
-        q.eq("connectionId", args.connectionId),
-      )
-      .first();
-
-    if (existing) {
-      await ctx.db.delete(existing._id);
-    }
-    return null;
-  },
-});
+// ─── Internal Token & Pending OAuth CRUD ─────────────────────────────────────
+// Called only from strava/public.ts. Not exposed to the host app.
+
+import { v } from "convex/values";
+import {
+  internalMutation,
+  internalQuery,
+} from "../_generated/server";
+
+// ─── Internal Pending OAuth CRUD ─────────────────────────────────────────────
+// Temporary storage for in-progress Strava OAuth flows.
+// Bridges getStravaAuthUrl and completeStravaOAuth.
+
+export const storePendingOAuth = internalMutation({
+  args: {
+    provider: v.string(),
+    state: v.string(),
+    userId: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.insert("pendingOAuth", {
+      ...args,
+      createdAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+export const getPendingOAuth = internalQuery({
+  args: { state: v.string() },
+  returns: v.union(
+    v.object({
+      _id: v.id("pendingOAuth"),
+      _creationTime: v.number(),
+      provider: v.string(),
+      state: v.string(),
+      userId: v.string(),
+      createdAt: v.number(),
+    }),
+    v.null(),
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("pendingOAuth")
+      .withIndex("by_state", (q) => q.eq("state", args.state))
+      .first();
+  },
+});
+
+export const deletePendingOAuth = internalMutation({
+  args: { state: v.string() },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const pending = await ctx.db
+      .query("pendingOAuth")
+      .withIndex("by_state", (q) => q.eq("state", args.state))
+      .first();
+    if (pending) {
+      await ctx.db.delete(pending._id);
+    }
+    return null;
+  },
+});
+
+// ─── Internal Token CRUD ─────────────────────────────────────────────────────
+
+/**
+ * Store or update OAuth tokens for a connection.
+ * Upserts by connectionId — one token record per connection.
+ */
+export const storeTokens = internalMutation({
+  args: {
+    connectionId: v.id("connections"),
+    accessToken: v.string(),
+    refreshToken: v.string(),
+    expiresAt: v.number(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("providerTokens")
+      .withIndex("by_connectionId", (q) =>
+        q.eq("connectionId", args.connectionId),
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.patch(existing._id, {
+        accessToken: args.accessToken,
+        refreshToken: args.refreshToken,
+        expiresAt: args.expiresAt,
+      });
+      return null;
+    }
+
+    await ctx.db.insert("providerTokens", args);
+    return null;
+  },
+});
+
+/**
+ * Get stored tokens for a connection.
+ */
+export const getTokens = internalQuery({
+  args: { connectionId: v.id("connections") },
+  returns: v.union(
+    v.object({
+      _id: v.id("providerTokens"),
+      _creationTime: v.number(),
+      connectionId: v.id("connections"),
+      accessToken: v.string(),
+      refreshToken: v.optional(v.string()),
+      expiresAt: v.optional(v.number()),
+    }),
+    v.null(),
+  ),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("providerTokens")
+      .withIndex("by_connectionId", (q) =>
+        q.eq("connectionId", args.connectionId),
+      )
+      .first();
+  },
+});
+
+/**
+ * Delete stored tokens for a connection.
+ */
+export const deleteTokens = internalMutation({
+  args: { connectionId: v.id("connections") },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("providerTokens")
+      .withIndex("by_connectionId", (q) =>
+        q.eq("connectionId", args.connectionId),
+      )
+      .first();
+
+    if (existing) {
+      await ctx.db.delete(existing._id);
+    }
+    return null;
+  },
+});