fix(settings): keep optional prefetch failures nonfatal

Author: waleedlatif1

.agents/skills/react-query-best-practices/SKILL.md

@@ -38,6 +38,7 @@ Read these before analyzing:
 - Compose caller-controlled `enabled` options with required-param guards (`Boolean(id) && (options?.enabled ?? true)`). Never spread options after an internal guard, because `{ enabled: true }` can silently re-enable an invalid request.
 - A disabled query can still report `isPending: true`. Aggregate loading state only for queries that are applicable/enabled, or an optional query can hold the whole surface in a permanent loading state.
 - Deferred authorization or policy queries must fail closed. Do not give pending/error data the same fallback as a successfully loaded unrestricted policy; disable guarded actions until the policy query succeeds.
+- Server prefetches must call the authorized use case, apply the route presenter/response schema, and reuse the client's exact key, mapper, and stale time. Keep all fallible auth/read/parse work inside `queryFn` so an optional warm cannot fail the page, and never bypass a route that redacts fields.
 
 ### Mutations
 - Use `onSettled` (not `onSuccess`) for cache reconciliation — it fires on both success and error

apps/sim/app/workspace/[workspaceId]/settings/[section]/page.tsx

@@ -207,13 +207,7 @@ export default async function WorkspaceSettingsSectionPage({
     }
   }
 
-  /**
-   * Scoped to the sections that actually read the key. The prefetch has to be awaited — an
-   * unsettled query is dropped from the dehydrated payload, so firing and forgetting would
-   * waterfall anyway — which means running it unconditionally charged the other ~25 sections
-   * a blocking round-trip for a cache entry they never touch. The viewer's profile is seeded
-   * by the workspace layout under a different key and is not repeated here.
-   */
+  /** Awaiting is required because unsettled queries are omitted from dehydration. */
   await sectionPrefetch
 
   return (

apps/sim/app/workspace/[workspaceId]/settings/[section]/prefetch.test.ts

@@ -64,7 +64,17 @@ describe('credential-groups prefetch', () => {
   })
 
   it('hydrates the key the panel subscribes to, through the authorized use case', async () => {
-    mockExecute.mockResolvedValue({ credentialGroups: [{ id: 'g1' }] })
+    const credentialGroup = {
+      id: 'g1',
+      workspaceId: 'w1',
+      name: 'Engineering',
+      description: null,
+      options: [],
+      status: 'active',
+      createdAt: '2026-01-01T00:00:00.000Z',
+      updatedAt: '2026-01-01T00:00:00.000Z',
+    }
+    mockExecute.mockResolvedValue({ credentialGroups: [{ ...credentialGroup, internal: true }] })
     const queryClient = new QueryClient()
 
     await SECTION_PREFETCHERS['credential-groups']?.(queryClient, {
@@ -76,12 +86,10 @@ describe('credential-groups prefetch', () => {
       principal: { kind: 'session', userId: 'u1', sessionId: 's1' },
       input: { workspaceId: 'w1' },
     })
-    expect(queryClient.getQueryData(credentialGroupKeys.list('w1'))).toEqual([{ id: 'g1' }])
+    expect(queryClient.getQueryData(credentialGroupKeys.list('w1'))).toEqual([credentialGroup])
   })
 
   it('leaves the cache empty when the use case denies the viewer', async () => {
-    // prefetchQuery swallows the rejection, so a denied viewer simply hydrates nothing and the
-    // client fetch renders the real error rather than a poisoned cache entry.
     mockExecute.mockRejectedValue(Object.assign(new Error('forbidden'), { code: 'forbidden' }))
     const queryClient = new QueryClient()
 
@@ -92,4 +100,17 @@ describe('credential-groups prefetch', () => {
 
     expect(queryClient.getQueryData(credentialGroupKeys.list('w1'))).toBeUndefined()
   })
+
+  it('leaves the cache empty when session authentication fails', async () => {
+    mockAuthenticate.mockRejectedValue(new Error('unauthenticated'))
+    const queryClient = new QueryClient()
+
+    await SECTION_PREFETCHERS['credential-groups']?.(queryClient, {
+      workspaceId: 'w1',
+      userId: 'u1',
+    })
+
+    expect(mockExecute).not.toHaveBeenCalled()
+    expect(queryClient.getQueryData(credentialGroupKeys.list('w1'))).toBeUndefined()
+  })
 })

apps/sim/app/workspace/[workspaceId]/settings/[section]/prefetch.ts

@@ -1,4 +1,5 @@
 import type { QueryClient } from '@tanstack/react-query'
+import { listCredentialGroupsContract } from '@/lib/api/contracts/credential-groups'
 import { internalSessionAuth } from '@/lib/api/server/routes/internal-json-route'
 import { listCredentialGroupSettings } from '@/lib/credential-groups/application/manage-groups'
 import { getUserSettings } from '@/lib/users/queries'
@@ -13,20 +14,7 @@ import {
   credentialGroupKeys,
 } from '@/hooks/queries/utils/credential-group-queries'
 
-/**
- * Prefetch general settings server-side via the shared data layer.
- *
- * Uses the same query key and mapper as the client `useGeneralSettings` hook, so the
- * hydrated entry is indistinguishable from one a client fetch produced.
- *
- * The authenticated caller supplies the viewer ID it already resolved. Re-reading the session
- * inside the query would add another dependency to a prefetch that is deliberately started as
- * soon as workspace access succeeds.
- *
- * Callers must await the returned promise before dehydration. Only a settled query is included
- * by the current dehydration policy, so dropping the promise would leave the panel to fetch on
- * the client as if it had never been prefetched.
- */
+/** Prefetches the same key and mapped value as `useGeneralSettings`. */
 export function prefetchGeneralSettings(queryClient: QueryClient, userId: string) {
   return queryClient.prefetchQuery({
     queryKey: generalSettingsKeys.settings(),
@@ -38,33 +26,20 @@ export function prefetchGeneralSettings(queryClient: QueryClient, userId: string
   })
 }
 
-/**
- * Prefetch the workspace's credential groups through the same authorized use case the route
- * runs, so the panel paints hydrated instead of blanking until its own fetch returns.
- *
- * The use case is the authorization boundary, not the route: `listCredentialGroupSettings` is a
- * `defineAuthorizedWorkspaceUseCase`, so it resolves canonical context, authorizes the principal
- * and asserts the entitlement before reading. Prefetching through it therefore applies exactly
- * the checks a client request would. Reaching past it to `listCredentialGroups` would not — most
- * settings reads authorize in their route handler, and calling their data layer directly from a
- * server component would skip that gate entirely.
- *
- * A denied or failed prefetch is not fatal: `prefetchQuery` swallows the rejection, nothing is
- * dehydrated for the key, and the client fetches normally and renders the real error.
- */
+/** Prefetches credential groups through the route's authorization and response boundaries. */
 async function prefetchCredentialGroups(
   queryClient: QueryClient,
   { workspaceId }: SettingsSectionPrefetchContext
 ) {
-  const principal = await internalSessionAuth.authenticate()
   return queryClient.prefetchQuery({
     queryKey: credentialGroupKeys.list(workspaceId),
     queryFn: async () => {
-      const { credentialGroups } = await listCredentialGroupSettings.execute({
+      const principal = await internalSessionAuth.authenticate()
+      const result = await listCredentialGroupSettings.execute({
         principal,
         input: { workspaceId },
       })
-      return credentialGroups
+      return listCredentialGroupsContract.response.schema.parse(result).credentialGroups
     },
     staleTime: CREDENTIAL_GROUP_LIST_STALE_TIME,
   })
@@ -76,25 +51,9 @@ export interface SettingsSectionPrefetchContext {
 }
 
 /**
- * The data a section needs on its first paint, keyed by section.
- *
- * A settings section otherwise pays three serial hops — the route payload, its lazily-loaded
- * chunk, and only then its own queries. Seeding the query cache here collapses the third into
- * the first, so the body renders populated the moment its chunk lands rather than blanking
- * again while it fetches.
- *
- * Deliberately sparse, and it should stay that way. Every entry is awaited before dehydration
- * (an unsettled query is dropped from the payload), so a prefetch sits in front of the section
- * it serves — one that is slow, or that most viewers never open, makes the page slower. Two
- * conditions gate entry: the read must go through something that authorizes the viewer itself,
- * and the hydrated value must match what the client hook stores under that key, mapper included.
- *
- * Sections absent here are absent on purpose. Most settings reads authorize in their route
- * handler rather than their data layer, so prefetching them means first lifting the check out of
- * the route — and a few must never be prefetched naively at all, because the route is also what
- * redacts their response (SSO strips the OIDC client secret; MCP withholds credential headers
- * from read-only members). Their `general`/`billing`/`admin` entries below cover a switch that
- * would otherwise paint its default and visibly flip.
+ * First-paint prefetches keyed by section. Keep this sparse: each entry blocks dehydration,
+ * must preserve authorization and route projection, and must match the client hook's cache shape.
+ * Never bypass a route that redacts sensitive fields.
  */
 export const SECTION_PREFETCHERS: Partial<
   Record<