merge(integrations): honest Polar sleep timeline, shared reconstruction, OAuth returns, status envelope

src/components/settings/__tests__/oauth-return-outcome.test.ts

@@ -0,0 +1,67 @@
+/**
+ * v1.17.1 (04-M1) — the WHOOP / Fitbit OAuth callbacks redirect back with
+ * `?whoop=connected|error` / `?fitbit=connected|error&reason=<tag>`, but the
+ * settings page only read the param for Withings/Polar/Oura — so a user
+ * returning from a WHOOP or Fitbit round-trip landed on a silently unchanged
+ * page. These pin the four-provider outcome parsing + reason-key resolution.
+ */
+import { describe, it, expect } from "vitest";
+
+import {
+  parseOAuthOutcome,
+  oauthReasonKey,
+} from "../integrations-section";
+
+describe("parseOAuthOutcome", () => {
+  it("reads a connected outcome for every OAuth provider", () => {
+    for (const p of ["polar", "oura", "whoop", "fitbit"] as const) {
+      expect(parseOAuthOutcome(`?${p}=connected`)).toEqual({
+        provider: p,
+        kind: "connected",
+      });
+    }
+  });
+
+  it("reads WHOOP + Fitbit error outcomes with their reason tag (the gap fix)", () => {
+    expect(parseOAuthOutcome("?whoop=error&reason=token")).toEqual({
+      provider: "whoop",
+      kind: "error",
+      reason: "token",
+    });
+    expect(parseOAuthOutcome("?fitbit=error&reason=expired")).toEqual({
+      provider: "fitbit",
+      kind: "error",
+      reason: "expired",
+    });
+  });
+
+  it("defaults a missing reason to 'unknown'", () => {
+    expect(parseOAuthOutcome("?whoop=error")).toEqual({
+      provider: "whoop",
+      kind: "error",
+      reason: "unknown",
+    });
+  });
+
+  it("returns null when no provider param is present", () => {
+    expect(parseOAuthOutcome("?foo=bar")).toBeNull();
+    expect(parseOAuthOutcome("")).toBeNull();
+  });
+});
+
+describe("oauthReasonKey", () => {
+  it("maps a known tag to the provider-specific key", () => {
+    expect(oauthReasonKey("whoop", "token")).toBe(
+      "settings.whoopOauthError.token",
+    );
+    expect(oauthReasonKey("fitbit", "expired")).toBe(
+      "settings.fitbitOauthError.expired",
+    );
+  });
+
+  it("falls back to generic for an unknown tag", () => {
+    expect(oauthReasonKey("whoop", "totally_unknown")).toBe(
+      "settings.whoopOauthError.generic",
+    );
+  });
+});

src/components/settings/integrations-section.tsx

@@ -8,11 +8,13 @@ import { toast } from "sonner";
 
 import { FitbitCard } from "@/components/settings/integrations/fitbit-card";
 import { NightscoutCard } from "@/components/settings/integrations/nightscout-card";
+import type { OAuthProviderStatus } from "@/components/settings/integrations/oauth-provider-card";
 import { OuraCard } from "@/components/settings/integrations/oura-card";
 import { PolarCard } from "@/components/settings/integrations/polar-card";
 import {
   pickStatus,
   useIntegrationStatuses,
+  type IntegrationStatusViewModel,
 } from "@/components/settings/integrations/shared";
 import { WhoopCard } from "@/components/settings/integrations/whoop-card";
 import { WithingsCard } from "@/components/settings/integrations/withings-card";
@@ -43,6 +45,97 @@ type WithingsOauthOutcome =
   | { kind: "connected" }
   | { kind: "error"; reason: string };
 
+/**
+ * The OAuth providers whose callbacks redirect back to the settings page with a
+ * `?<provider>=connected|error&reason=<tag>` outcome param. Polar/Oura own a
+ * per-card status query; WHOOP/Fitbit read off the consolidated envelope — both
+ * are invalidated on a successful return so the card repaints either way.
+ */
+const OAUTH_OUTCOME_PROVIDERS = ["polar", "oura", "whoop", "fitbit"] as const;
+type OAuthOutcomeProvider = (typeof OAUTH_OUTCOME_PROVIDERS)[number];
+
+const OAUTH_OUTCOME_KEYS: Record<
+  OAuthOutcomeProvider,
+  () => readonly unknown[]
+> = {
+  polar: queryKeys.polar,
+  oura: queryKeys.oura,
+  whoop: queryKeys.whoop,
+  fitbit: queryKeys.fitbit,
+};
+
+/**
+ * Reason tags the four OAuth callbacks emit. Known tags resolve to a specific
+ * message; anything else falls back to the provider's `generic` copy. Union of
+ * the Polar/Oura set (`rate_limited`) and the WHOOP/Fitbit set (`expired`).
+ */
+const OAUTH_OUTCOME_REASONS = new Set([
+  "csrf1",
+  "state",
+  "cross_user",
+  "nocode",
+  "nocreds",
+  "token",
+  "rate_limited",
+  "expired",
+]);
+
+type OAuthOutcome =
+  | { provider: OAuthOutcomeProvider; kind: "connected" }
+  | { provider: OAuthOutcomeProvider; kind: "error"; reason: string };
+
+/**
+ * Parse the OAuth-return outcome from a URL query string. Reads the first
+ * provider whose `?<provider>=connected|error` param is present, in
+ * `OAUTH_OUTCOME_PROVIDERS` order. Pure + exported so the four-provider
+ * coverage is unit-testable without a browser.
+ */
+export function parseOAuthOutcome(search: string): OAuthOutcome | null {
+  const params = new URLSearchParams(search);
+  for (const provider of OAUTH_OUTCOME_PROVIDERS) {
+    const v = params.get(provider);
+    if (v === "connected") return { provider, kind: "connected" };
+    if (v === "error") {
+      return { provider, kind: "error", reason: params.get("reason") ?? "unknown" };
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve the i18n key for an error reason tag. Known tags map to the
+ * provider-specific message; anything else falls back to `generic`.
+ */
+export function oauthReasonKey(
+  provider: OAuthOutcomeProvider,
+  reason: string,
+): string {
+  return OAUTH_OUTCOME_REASONS.has(reason)
+    ? `settings.${provider}OauthError.${reason}`
+    : `settings.${provider}OauthError.generic`;
+}
+
+/**
+ * Adapt the consolidated-envelope view-model into the OAuth card's status
+ * shape. Returns `undefined` when the envelope hasn't loaded so the card
+ * renders its loading/disconnected default rather than a half-populated state.
+ */
+function toOAuthStatus(
+  vm: IntegrationStatusViewModel | undefined,
+): OAuthProviderStatus | undefined {
+  if (!vm) return undefined;
+  return {
+    connected: vm.connected ?? false,
+    configured: vm.configured ?? false,
+    available: vm.available ?? false,
+    hasOwnCredentials: vm.hasOwnCredentials,
+    state: vm.state,
+    lastSuccessAt: vm.lastSuccessAt,
+    lastAttemptAt: vm.lastAttemptAt,
+    lastError: vm.lastError,
+  };
+}
+
 export function IntegrationsSection() {
   const { t } = useTranslations();
   const { isAuthenticated } = useAuth();
@@ -92,23 +185,16 @@ export function IntegrationsSection() {
     }
   }, [withingsOauthOutcome, router, queryClient, t]);
 
-  // v1.17.0 (F4) — generic OAuth-callback toast for the env-based providers.
-  // The Polar / Oura callbacks redirect back with `?<provider>=connected` or
-  // `?<provider>=error&reason=<tag>`; surface the outcome as a toast and scrub
-  // the one-shot params so a reload doesn't replay it.
-  const [oauthOutcome] = useState<
-    { provider: "polar" | "oura"; kind: "connected" } | { provider: "polar" | "oura"; kind: "error"; reason: string } | null
-  >(() => {
+  // v1.17.0 (F4) — generic OAuth-callback toast for the OAuth providers.
+  // The Polar / Oura / WHOOP / Fitbit callbacks redirect back with
+  // `?<provider>=connected` or `?<provider>=error&reason=<tag>`; surface the
+  // outcome as a toast and scrub the one-shot params so a reload doesn't replay
+  // it. Pre-v1.17.1 only Polar/Oura were read here — a user returning from a
+  // WHOOP or Fitbit round-trip landed on a silently unchanged settings page,
+  // the same gap the Withings handler was written to close.
+  const [oauthOutcome] = useState<OAuthOutcome | null>(() => {
     if (typeof window === "undefined") return null;
-    const params = new URLSearchParams(window.location.search);
-    for (const provider of ["polar", "oura"] as const) {
-      const v = params.get(provider);
-      if (v === "connected") return { provider, kind: "connected" };
-      if (v === "error") {
-        return { provider, kind: "error", reason: params.get("reason") ?? "unknown" };
-      }
-    }
-    return null;
+    return parseOAuthOutcome(window.location.search);
   });
 
   useEffect(() => {
@@ -118,27 +204,19 @@ export function IntegrationsSection() {
     url.searchParams.delete(provider);
     url.searchParams.delete("reason");
     router.replace(`${url.pathname}${url.search}`, { scroll: false });
-    const key = provider === "polar" ? queryKeys.polar() : queryKeys.oura();
     if (oauthOutcome.kind === "connected") {
       toast.success(t(`settings.${provider}OauthConnected`));
-      queryClient.invalidateQueries({ queryKey: key });
+      // Polar/Oura own a per-card status query; WHOOP/Fitbit read off the
+      // consolidated envelope — invalidate both so the card repaints either way.
+      queryClient.invalidateQueries({ queryKey: OAUTH_OUTCOME_KEYS[provider]() });
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.integrationsStatus(),
+      });
     } else {
       // Known reason tags resolve to a specific message; anything else falls
       // back to the generic copy (matching the Withings handler).
-      const knownReasons = new Set([
-        "csrf1",
-        "state",
-        "cross_user",
-        "nocode",
-        "nocreds",
-        "token",
-        "rate_limited",
-      ]);
-      const reasonKey = knownReasons.has(oauthOutcome.reason)
-        ? `settings.${provider}OauthError.${oauthOutcome.reason}`
-        : `settings.${provider}OauthError.generic`;
       toast.error(t(`settings.${provider}OauthFailed`), {
-        description: t(reasonKey),
+        description: t(oauthReasonKey(provider, oauthOutcome.reason)),
         duration: 10_000,
       });
     }
@@ -147,6 +225,10 @@ export function IntegrationsSection() {
   const withingsViewModel = pickStatus(integrationStatus, "withings");
   const whoopViewModel = pickStatus(integrationStatus, "whoop");
   const fitbitViewModel = pickStatus(integrationStatus, "fitbit");
+  // v1.17.1 — Polar/Oura now read off the same consolidated envelope; the cards
+  // no longer fire their own /api/<provider>/status round-trip.
+  const polarViewModel = toOAuthStatus(pickStatus(integrationStatus, "polar"));
+  const ouraViewModel = toOAuthStatus(pickStatus(integrationStatus, "oura"));
 
   return (
     <section
@@ -179,8 +261,8 @@ export function IntegrationsSection() {
       <WithingsCard viewModel={withingsViewModel} />
       <WhoopCard viewModel={whoopViewModel} />
       <FitbitCard viewModel={fitbitViewModel} />
-      <PolarCard enabled={isAuthenticated} />
-      <OuraCard enabled={isAuthenticated} />
+      <PolarCard enabled={isAuthenticated} viewModel={polarViewModel} />
+      <OuraCard enabled={isAuthenticated} viewModel={ouraViewModel} />
       <NightscoutCard enabled={isAuthenticated} />
     </section>
   );

src/components/settings/integrations/__tests__/oauth-provider-card.test.tsx

@@ -23,7 +23,13 @@ vi.mock("@tanstack/react-query", () => ({
 import { I18nProvider } from "@/lib/i18n/context";
 import { OAuthProviderCard } from "../oauth-provider-card";
 
-function render({ credentials = false }: { credentials?: boolean } = {}) {
+function render({
+  credentials = false,
+  viewModel,
+}: {
+  credentials?: boolean;
+  viewModel?: Parameters<typeof OAuthProviderCard>[0]["viewModel"];
+} = {}) {
   return renderToStaticMarkup(
     <I18nProvider initialLocale="en">
       <OAuthProviderCard
@@ -33,6 +39,7 @@ function render({ credentials = false }: { credentials?: boolean } = {}) {
         icon={Watch}
         dataHref="/insights/sleep"
         credentials={credentials}
+        viewModel={viewModel}
       />
     </I18nProvider>,
   );
@@ -74,6 +81,25 @@ describe("OAuthProviderCard — parked + test + data-link parity", () => {
     expect(html).toContain('href="/insights/sleep"');
   });
 
+  it("reads off the passed view-model instead of the per-card fetch (04-M2)", () => {
+    // The per-card useQuery mock returns null; the card must render the
+    // connected state from the supplied envelope view-model alone, proving the
+    // /api/<provider>/status round-trip is no longer the source.
+    statusPayload = null;
+    const html = render({
+      viewModel: {
+        connected: true,
+        configured: true,
+        available: true,
+        state: "connected",
+        lastSuccessAt: "2026-06-01T00:00:00.000Z",
+        lastError: null,
+      },
+    });
+    expect(html).toContain('data-testid="polar-data-link"');
+    expect(html).toContain("Test connection");
+  });
+
   it("does not render the data link or test button when disconnected", () => {
     statusPayload = {
       connected: false,

src/components/settings/integrations/oauth-provider-card.tsx

@@ -36,7 +36,11 @@ import {
 import { TestConnectionButton } from "@/components/settings/test-connection-button";
 import { apiFetchRaw, apiGet, apiPost } from "@/lib/api/api-fetch";
 import { useTranslations } from "@/lib/i18n/context";
-import { invalidateKeys, measurementDependentKeys } from "@/lib/query-keys";
+import {
+  invalidateKeys,
+  measurementDependentKeys,
+  queryKeys,
+} from "@/lib/query-keys";
 import { IntegrationSetupGuideLink } from "./setup-guide-link";
 
 export interface OAuthProviderStatus {
@@ -85,6 +89,13 @@ export interface OAuthProviderCardProps {
    * button. The endpoint is the PUT target (e.g. `/api/polar/credentials`). */
   credentials?: boolean;
   enabled?: boolean;
+  /**
+   * When provided, the card reads its status from this view-model (sourced off
+   * the consolidated `/api/integrations/status` envelope) instead of firing its
+   * own `/api/<provider>/status` round-trip. v1.17.1 folds Polar/Oura onto the
+   * same envelope WHOOP/Fitbit already use, so the page reads from one source.
+   */
+  viewModel?: OAuthProviderStatus;
 }
 
 export function OAuthProviderCard({
@@ -95,6 +106,7 @@ export function OAuthProviderCard({
   dataHref,
   credentials = false,
   enabled = true,
+  viewModel,
 }: OAuthProviderCardProps) {
   const { t } = useTranslations();
   const queryClient = useQueryClient();
@@ -107,12 +119,17 @@ export function OAuthProviderCard({
     null,
   );
 
-  const { data: status } = useQuery({
+  // Read off the consolidated envelope when a view-model is passed; otherwise
+  // fall back to the per-card status fetch (still used by any caller that has
+  // not been migrated onto the envelope). The fetch is disabled once a
+  // view-model is supplied so the page makes one request, not one-per-card.
+  const { data: fetchedStatus } = useQuery({
     queryKey: statusQueryKey,
     queryFn: async () => apiGet<OAuthProviderStatus>(`/api/${provider}/status`),
-    enabled,
+    enabled: enabled && !viewModel,
     refetchOnWindowFocus: true,
   });
+  const status = viewModel ?? fetchedStatus;
 
   async function handleSaveCredentials(e: React.FormEvent) {
     e.preventDefault();
@@ -134,6 +151,11 @@ export function OAuthProviderCard({
         setClientId("");
         setClientSecret("");
         queryClient.invalidateQueries({ queryKey: statusQueryKey });
+        // The card may read off the consolidated envelope — invalidate it too
+        // so the saved-credentials state repaints regardless of the source.
+        queryClient.invalidateQueries({
+          queryKey: queryKeys.integrationsStatus(),
+        });
       } else {
         try {
           const json = await res.json();
@@ -156,6 +178,9 @@ export function OAuthProviderCard({
     },
     onSuccess: () => {
       queryClient.invalidateQueries({ queryKey: statusQueryKey });
+      queryClient.invalidateQueries({
+        queryKey: queryKeys.integrationsStatus(),
+      });
     },
   });
 

src/components/settings/integrations/oura-card.tsx

@@ -6,10 +6,19 @@
 
 import { CircleDot } from "lucide-react";
 
-import { OAuthProviderCard } from "@/components/settings/integrations/oauth-provider-card";
+import {
+  OAuthProviderCard,
+  type OAuthProviderStatus,
+} from "@/components/settings/integrations/oauth-provider-card";
 import { queryKeys } from "@/lib/query-keys";
 
-export function OuraCard({ enabled = true }: { enabled?: boolean }) {
+export function OuraCard({
+  enabled = true,
+  viewModel,
+}: {
+  enabled?: boolean;
+  viewModel?: OAuthProviderStatus;
+}) {
   return (
     <OAuthProviderCard
       provider="oura"
@@ -19,6 +28,7 @@ export function OuraCard({ enabled = true }: { enabled?: boolean }) {
       dataHref="/insights/sleep"
       credentials
       enabled={enabled}
+      viewModel={viewModel}
     />
   );
 }

src/components/settings/integrations/polar-card.tsx

@@ -6,10 +6,19 @@
 
 import { Watch } from "lucide-react";
 
-import { OAuthProviderCard } from "@/components/settings/integrations/oauth-provider-card";
+import {
+  OAuthProviderCard,
+  type OAuthProviderStatus,
+} from "@/components/settings/integrations/oauth-provider-card";
 import { queryKeys } from "@/lib/query-keys";
 
-export function PolarCard({ enabled = true }: { enabled?: boolean }) {
+export function PolarCard({
+  enabled = true,
+  viewModel,
+}: {
+  enabled?: boolean;
+  viewModel?: OAuthProviderStatus;
+}) {
   return (
     <OAuthProviderCard
       provider="polar"
@@ -19,6 +28,7 @@ export function PolarCard({ enabled = true }: { enabled?: boolean }) {
       dataHref="/insights/sleep"
       credentials
       enabled={enabled}
+      viewModel={viewModel}
     />
   );
 }

src/components/settings/integrations/shared.tsx

@@ -18,7 +18,13 @@ import { queryKeys } from "@/lib/query-keys";
 // v1.4.19 Phase A5: the redundant in-card status banner is gone — the
 // IntegrationStatusPill now owns state + last-sync presentation, and
 // the actionable error message is shown inline above the action row.
-export type IntegrationKey = "withings" | "whoop" | "fitbit" | "moodlog";
+export type IntegrationKey =
+  | "withings"
+  | "whoop"
+  | "fitbit"
+  | "moodlog"
+  | "polar"
+  | "oura";
 export type IntegrationState =
   | "connected"
   | "error_transient"
@@ -52,6 +58,11 @@ export interface IntegrationStatusViewModel {
   // moodLog webhook secret + entry count.
   webhookSecret?: string | null;
   entryCount?: number;
+  // Polar / Oura OAuth card: usable-credentials + BYO-key flags. `available`
+  // greys out the connect button when no credentials resolve; `hasOwnCredentials`
+  // drives the saved-placeholder UI.
+  available?: boolean;
+  hasOwnCredentials?: boolean;
 }
 
 export interface IntegrationStatusEnvelope {