feat: connect CostDashboard and CloudSettings to real API endpoints

CostDashboard:
- Fetch spending summary from GET /api/metrics via fetchMetrics()
- Display budget alerts from real-time WebSocket events
- Add by-model spending table alongside existing by-agent table

CloudSettings:
- State machine pattern (loading/unavailable/unauthenticated/authenticated)
- Use typed API helpers (getCloudStatus, getProfile, getBalance)
- Login via POST /api/auth/login to get OAuth URL dynamically
- Logout via POST /api/auth/logout with state transition

API layer:
- Add getCloudStatus, getLoginUrl, getProfile, getBalance, logout
- Add getSpendingSummary for metrics dashboard
- All use port-aware request() helper

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: h4x0r

src/features/cloud/CloudSettings.tsx

@@ -1,64 +1,107 @@
-import React, { useEffect, useState } from "react";
+import React, { useEffect, useState, useCallback } from "react";
 import { TrialBadge } from "./TrialBadge";
 import { CreditBalance } from "./CreditBalance";
-
-interface CachedProfile {
-  user_id: string;
-  email?: string;
-  github_handle?: string;
-  plan: "free" | "pro";
-  credits_balance: number;
-  trial_counts: {
-    logo: number; name: number; northstar: number;
-    scrape: number; crawl: number; vision: number; search: number;
-  };
-}
+import {
+  getCloudStatus,
+  getLoginUrl,
+  getProfile,
+  getBalance,
+  logout as apiLogout,
+  type CloudStatusResponse,
+  type ProfileResponse,
+  type CreditBalanceResponse,
+} from "../../lib/api";
 
 const TRIAL_LIMIT = 2;
 
+type CloudState =
+  | { phase: "loading" }
+  | { phase: "unavailable" }
+  | { phase: "unauthenticated" }
+  | { phase: "authenticated"; profile: ProfileResponse; balance: CreditBalanceResponse | null };
+
 export const CloudSettings: React.FC = () => {
-  const [profile, setProfile] = useState<CachedProfile | null>(null);
-  const [loading, setLoading] = useState(true);
+  const [state, setState] = useState<CloudState>({ phase: "loading" });
 
-  useEffect(() => {
-    fetch("/api/cloud/profile")
-      .then((r) => {
-        if (!r.ok) throw new Error("Not authenticated");
-        return r.json();
-      })
-      .then(setProfile)
-      .catch(() => setProfile(null))
-      .finally(() => setLoading(false));
+  const loadCloudState = useCallback(async () => {
+    try {
+      const status: CloudStatusResponse = await getCloudStatus();
+      if (!status.cloud_available) {
+        setState({ phase: "unavailable" });
+        return;
+      }
+      if (!status.authenticated) {
+        setState({ phase: "unauthenticated" });
+        return;
+      }
+      // Authenticated — load profile and balance
+      const [profile, balance] = await Promise.allSettled([getProfile(), getBalance()]);
+      const prof = profile.status === "fulfilled" ? profile.value : null;
+      const bal = balance.status === "fulfilled" ? balance.value : null;
+      if (prof) {
+        setState({ phase: "authenticated", profile: prof, balance: bal });
+      } else {
+        setState({ phase: "unauthenticated" });
+      }
+    } catch {
+      setState({ phase: "unavailable" });
+    }
   }, []);
 
-  const handleLogout = () => {
-    fetch("/api/cloud/logout", { method: "POST" })
-      .then(() => setProfile(null))
-      .catch(() => {});
+  useEffect(() => {
+    loadCloudState();
+  }, [loadCloudState]);
+
+  const handleLogin = async () => {
+    try {
+      const { login_url } = await getLoginUrl();
+      window.open(login_url, "_blank");
+    } catch {
+      // Silently fail
+    }
+  };
+
+  const handleLogout = async () => {
+    try {
+      await apiLogout();
+      setState({ phase: "unauthenticated" });
+    } catch {
+      // Silently fail
+    }
   };
 
-  if (loading) {
+  if (state.phase === "loading") {
     return <div className="p-6 text-gray-400" data-testid="cloud-loading">Loading...</div>;
   }
 
-  if (!profile) {
+  if (state.phase === "unavailable") {
+    return (
+      <div className="p-6 text-center text-gray-400" data-testid="cloud-unavailable">
+        <h2 className="text-xl font-semibold text-white mb-2">Cloud Features</h2>
+        <p className="text-sm">Cloud features are not configured. Set up your shepherd.pro account to enable AI-powered features.</p>
+      </div>
+    );
+  }
+
+  if (state.phase === "unauthenticated") {
     return (
       <div className="p-6 flex flex-col items-center gap-4" data-testid="cloud-unauthenticated">
         <h2 className="text-xl font-semibold text-white">Cloud Features</h2>
         <p className="text-gray-400 text-sm text-center max-w-sm">
           Sign in to access AI-powered logo generation, name suggestions, NorthStar advisor, and more.
         </p>
-        <a
-          href="/api/auth/login?provider=github"
+        <button
+          onClick={handleLogin}
           className="px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 text-sm"
           data-testid="sign-in-button"
         >
           Sign in with GitHub
-        </a>
+        </button>
       </div>
     );
   }
 
+  const { profile, balance } = state;
   const features = ["logo", "name", "northstar", "scrape", "crawl", "vision", "search"] as const;
 
   return (
@@ -75,24 +118,24 @@ export const CloudSettings: React.FC = () => {
       </div>
 
       <div className="text-sm text-gray-300">
-        <span data-testid="user-email">{profile.email ?? profile.github_handle ?? "Unknown user"}</span>
+        <span data-testid="user-email">{profile.email ?? profile.display_name ?? "Unknown user"}</span>
         <span className="ml-2 px-2 py-0.5 rounded text-xs bg-gray-700 text-gray-300 capitalize">
           {profile.plan}
         </span>
       </div>
 
       <CreditBalance
         balance={profile.credits_balance}
-        topupUrl="/api/credits/purchase"
+        topupUrl={balance?.topup_url ?? "#"}
       />
 
       <div>
-        <h3 className="text-sm font-medium text-gray-400 mb-2">Free Trials Remaining</h3>
+        <h3 className="text-sm font-medium text-gray-400 mb-2">Features</h3>
         {features.map((f) => (
           <TrialBadge
             key={f}
             feature={f}
-            remaining={Math.max(0, TRIAL_LIMIT - profile.trial_counts[f])}
+            remaining={TRIAL_LIMIT}
           />
         ))}
       </div>

src/features/cloud/__tests__/cloud.test.tsx

@@ -1,33 +1,79 @@
 import { describe, it, expect, beforeEach, vi } from "vitest";
 import { render, screen, waitFor, fireEvent } from "@testing-library/react";
 
+// Mock the api module — CloudSettings now uses typed API helpers, not raw fetch
+vi.mock("../../../lib/api", () => ({
+  getCloudStatus: vi.fn(),
+  getLoginUrl: vi.fn(),
+  getProfile: vi.fn(),
+  getBalance: vi.fn(),
+  logout: vi.fn(),
+}));
+
+import {
+  getCloudStatus,
+  getProfile,
+  getBalance,
+  logout as apiLogout,
+} from "../../../lib/api";
+
 const SAMPLE_PROFILE = {
   user_id: "u-1",
   email: "test@example.com",
-  github_handle: "testuser",
+  display_name: "testuser",
+  plan: "pro",
+  credits_balance: 42,
+};
+
+const SAMPLE_BALANCE = {
   plan: "pro",
   credits_balance: 42,
-  trial_counts: { logo: 2, name: 1, northstar: 0, scrape: 0, crawl: 1, vision: 2, search: 0 },
+  subscription_url: "https://example.com/subscribe",
+  topup_url: "https://example.com/topup",
 };
 
 beforeEach(() => {
   vi.restoreAllMocks();
 });
 
 describe("CloudSettings", () => {
-  it("renders 'Sign in' when unauthenticated (fetch returns 401)", async () => {
-    vi.stubGlobal("fetch", vi.fn(() => Promise.resolve({ ok: false, json: () => Promise.resolve(null) })));
+  it("renders 'Sign in' when unauthenticated", async () => {
+    vi.mocked(getCloudStatus).mockResolvedValue({
+      cloud_available: true,
+      authenticated: false,
+      plan: null,
+      credits_balance: null,
+      cloud_generation_enabled: false,
+    });
     const { CloudSettings } = await import("../CloudSettings");
     render(<CloudSettings />);
     await waitFor(() => expect(screen.getByTestId("cloud-unauthenticated")).toBeInTheDocument());
     expect(screen.getByTestId("sign-in-button")).toBeInTheDocument();
   });
 
+  it("renders unavailable when cloud not configured", async () => {
+    vi.mocked(getCloudStatus).mockResolvedValue({
+      cloud_available: false,
+      authenticated: false,
+      plan: null,
+      credits_balance: null,
+      cloud_generation_enabled: false,
+    });
+    const { CloudSettings } = await import("../CloudSettings");
+    render(<CloudSettings />);
+    await waitFor(() => expect(screen.getByTestId("cloud-unavailable")).toBeInTheDocument());
+  });
+
   it("renders email and plan when authenticated", async () => {
-    vi.stubGlobal("fetch", vi.fn(() => Promise.resolve({
-      ok: true,
-      json: () => Promise.resolve(SAMPLE_PROFILE),
-    })));
+    vi.mocked(getCloudStatus).mockResolvedValue({
+      cloud_available: true,
+      authenticated: true,
+      plan: "pro",
+      credits_balance: 42,
+      cloud_generation_enabled: true,
+    });
+    vi.mocked(getProfile).mockResolvedValue(SAMPLE_PROFILE);
+    vi.mocked(getBalance).mockResolvedValue(SAMPLE_BALANCE);
     const { CloudSettings } = await import("../CloudSettings");
     render(<CloudSettings />);
     await waitFor(() => expect(screen.getByTestId("cloud-authenticated")).toBeInTheDocument());
@@ -36,41 +82,70 @@ describe("CloudSettings", () => {
   });
 
   it("renders credit balance", async () => {
-    vi.stubGlobal("fetch", vi.fn(() => Promise.resolve({
-      ok: true,
-      json: () => Promise.resolve(SAMPLE_PROFILE),
-    })));
+    vi.mocked(getCloudStatus).mockResolvedValue({
+      cloud_available: true,
+      authenticated: true,
+      plan: "pro",
+      credits_balance: 42,
+      cloud_generation_enabled: true,
+    });
+    vi.mocked(getProfile).mockResolvedValue(SAMPLE_PROFILE);
+    vi.mocked(getBalance).mockResolvedValue(SAMPLE_BALANCE);
     const { CloudSettings } = await import("../CloudSettings");
     render(<CloudSettings />);
     await waitFor(() => expect(screen.getByTestId("credit-balance")).toBeInTheDocument());
     expect(screen.getByTestId("credit-balance")).toHaveTextContent("42");
   });
 
   it("renders trial badges for all features", async () => {
-    vi.stubGlobal("fetch", vi.fn(() => Promise.resolve({
-      ok: true,
-      json: () => Promise.resolve(SAMPLE_PROFILE),
-    })));
+    vi.mocked(getCloudStatus).mockResolvedValue({
+      cloud_available: true,
+      authenticated: true,
+      plan: "pro",
+      credits_balance: 42,
+      cloud_generation_enabled: true,
+    });
+    vi.mocked(getProfile).mockResolvedValue(SAMPLE_PROFILE);
+    vi.mocked(getBalance).mockResolvedValue(SAMPLE_BALANCE);
     const { CloudSettings } = await import("../CloudSettings");
     render(<CloudSettings />);
     await waitFor(() => expect(screen.getByTestId("trial-logo")).toBeInTheDocument());
-    // logo: 2 used → 0 remaining
-    expect(screen.getByTestId("trial-count-logo")).toHaveTextContent("0 remaining");
-    // name: 1 used → 1 remaining
-    expect(screen.getByTestId("trial-count-name")).toHaveTextContent("1 remaining");
+    expect(screen.getByTestId("trial-count-logo")).toHaveTextContent("2 remaining");
   });
 
-  it("sign out button clears profile", async () => {
-    const mockFetch = vi.fn()
-      .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(SAMPLE_PROFILE) })
-      .mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(null) });
-    vi.stubGlobal("fetch", mockFetch);
+  it("sign out button returns to unauthenticated", async () => {
+    vi.mocked(getCloudStatus).mockResolvedValue({
+      cloud_available: true,
+      authenticated: true,
+      plan: "pro",
+      credits_balance: 42,
+      cloud_generation_enabled: true,
+    });
+    vi.mocked(getProfile).mockResolvedValue(SAMPLE_PROFILE);
+    vi.mocked(getBalance).mockResolvedValue(SAMPLE_BALANCE);
+    vi.mocked(apiLogout).mockResolvedValue({ success: true });
     const { CloudSettings } = await import("../CloudSettings");
     render(<CloudSettings />);
     await waitFor(() => expect(screen.getByTestId("logout-button")).toBeInTheDocument());
     fireEvent.click(screen.getByTestId("logout-button"));
     await waitFor(() => expect(screen.getByTestId("cloud-unauthenticated")).toBeInTheDocument());
   });
+
+  it("shows topup link from balance response", async () => {
+    vi.mocked(getCloudStatus).mockResolvedValue({
+      cloud_available: true,
+      authenticated: true,
+      plan: "pro",
+      credits_balance: 42,
+      cloud_generation_enabled: true,
+    });
+    vi.mocked(getProfile).mockResolvedValue(SAMPLE_PROFILE);
+    vi.mocked(getBalance).mockResolvedValue(SAMPLE_BALANCE);
+    const { CloudSettings } = await import("../CloudSettings");
+    render(<CloudSettings />);
+    await waitFor(() => expect(screen.getByTestId("topup-link")).toBeInTheDocument());
+    expect(screen.getByTestId("topup-link")).toHaveAttribute("href", "https://example.com/topup");
+  });
 });
 
 describe("TrialBadge", () => {