fix: report credential-safe key validation failures

src/lib/api.test.ts

@@ -1,24 +1,11 @@
-import { beforeEach, expect, test, vi } from 'vitest'
-
-const { get, post } = vi.hoisted(() => ({
-  get: vi.fn(),
-  post: vi.fn(),
-}))
-
-vi.mock('@seamapi/http', () => ({
-  isSeamHttpApiError: () => false,
-  isSeamHttpUnauthorizedError: () => false,
-  SeamHttpInvalidTokenError: class extends Error {},
-  SeamHttpWorkspaces: class {
-    get = get
-    client = { post }
-  },
-}))
+import { SeamHttpInvalidTokenError } from '@seamapi/http'
+import { afterEach, expect, test, vi } from 'vitest'
 
 import { exchangeWizardInferenceToken, getWorkspaceForApiKey } from './api.js'
 
-beforeEach(() => vi.clearAllMocks())
+afterEach(() => vi.unstubAllGlobals())
 
+// Fixed noncredential fixtures; all requests stop at the fetch boundary.
 test('uses the workspace SDK and its raw client', async () => {
   const workspace = {
     workspace_id: 'workspace-1',
@@ -33,18 +20,114 @@ test('uses the workspace SDK and its raw client', async () => {
     embed_customer_portal: null,
     device_categories: ['locks'],
   }
-  get.mockResolvedValue(workspace)
-  post.mockResolvedValue({
-    data: {
-      wizard_session: { token: 'token', expires_at: 'tomorrow', onboarding },
-    },
-  })
-
-  await expect(getWorkspaceForApiKey('seam_key')).resolves.toBe(workspace)
+  const requests: Request[] = []
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async (request: Request) => {
+      requests.push(request)
+      return Response.json(
+        request.url.endsWith('/session')
+          ? {
+              wizard_session: {
+                token: 'token',
+                expires_at: 'tomorrow',
+                onboarding,
+              },
+            }
+          : { workspace },
+      )
+    }),
+  )
+  await expect(getWorkspaceForApiKey('seam_key')).resolves.toEqual(workspace)
   await expect(exchangeWizardInferenceToken('seam_key')).resolves.toEqual({
     token: 'token',
     expires_at: 'tomorrow',
     onboarding,
   })
-  expect(post).toHaveBeenCalledWith('/seam/wizard/v1/session', {})
+  expect(new URL(requests[1]?.url ?? '').pathname).toBe(
+    '/seam/wizard/v1/session',
+  )
+  expect(await requests[1]?.json()).toEqual({})
+})
+
+test('malformed and wrong token types preserve the native local error', async () => {
+  const fetch = vi.fn()
+  vi.stubGlobal('fetch', fetch)
+  for (const token of ['not-a-key', 'seam_pk_not-a-key']) {
+    await expect(getWorkspaceForApiKey(token)).rejects.toBeInstanceOf(
+      SeamHttpInvalidTokenError,
+    )
+  }
+  expect(fetch).not.toHaveBeenCalled()
+})
+
+test.each(['json', 'text'])(
+  'an actual unauthorized %s response reports 401',
+  async (format) => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async () =>
+        format === 'json'
+          ? Response.json({}, { status: 401 })
+          : new Response('secret-marker', { status: 401 }),
+      ),
+    )
+    await expect(getWorkspaceForApiKey('seam_key')).rejects.toMatchObject({
+      name: 'SeamHttpUnauthorizedError',
+      statusCode: 401,
+    })
+  },
+)
+
+test('a 5xx response preserves the native SDK exception and details', async () => {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async () =>
+      Response.json(
+        { error: { type: 'internal_error', message: 'secret-marker' } },
+        { status: 503 },
+      ),
+    ),
+  )
+  await expect(getWorkspaceForApiKey('seam_key')).rejects.toMatchObject({
+    name: 'SeamHttpApiError',
+    statusCode: 503,
+    message: 'secret-marker',
+  })
+})
+
+test('fetch transport failures preserve the SDK transport exception', async () => {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async () => {
+      throw new TypeError('Failed to fetch secret-marker')
+    }),
+  )
+  await expect(getWorkspaceForApiKey('seam_key')).rejects.toMatchObject({
+    code: 'ERR_NETWORK',
+  })
+})
+
+test('non-JSON HTTP failures retain their known status', async () => {
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async () => new Response('secret-marker', { status: 502 })),
+  )
+  await expect(getWorkspaceForApiKey('seam_key')).rejects.toMatchObject({
+    response: { status: 502 },
+  })
+})
+
+test('the SDK transport exception retains its original cause', async () => {
+  const original = new TypeError('secret-marker')
+  vi.stubGlobal(
+    'fetch',
+    vi.fn(async () => {
+      throw original
+    }),
+  )
+  await expect(getWorkspaceForApiKey('seam_key')).rejects.toMatchObject({
+    isAxiosError: true,
+    cause: original,
+  })
 })

src/lib/api.ts

@@ -1,12 +1,11 @@
 import {
   isSeamHttpApiError,
-  isSeamHttpUnauthorizedError,
-  SeamHttpInvalidTokenError,
   SeamHttpWorkspaces,
   type Workspace,
 } from '@seamapi/http'
 
 import { getAuth } from 'lib/adapter.js'
+import { markConnectionFailure } from 'lib/connection-error.js'
 
 export function getApiBaseUrl(): string {
   return getAuth().endpoint.replace(/\/+$/, '')
@@ -28,22 +27,7 @@ export async function getWorkspaceForApiKey(
   try {
     return await getApi(apiKey).get()
   } catch (error) {
-    if (
-      error instanceof SeamHttpInvalidTokenError ||
-      isSeamHttpUnauthorizedError(error)
-    ) {
-      throw new ApiKeyError(
-        'That key was rejected (401). Make sure you copied the full key, including the seam_ prefix.',
-      )
-    }
-    if (isSeamHttpApiError(error)) {
-      throw new ApiKeyError(
-        `The Seam API returned ${error.statusCode}. Please try again in a moment.`,
-      )
-    }
-    throw new ApiKeyError(
-      'Could not reach the Seam API. Check your network connection and try again.',
-    )
+    throw markConnectionFailure(error, 'key_validation')
   }
 }
 

src/lib/app.tsx

@@ -19,13 +19,13 @@ import {
   trackScreen,
 } from './analytics.js'
 import {
-  ApiKeyError,
   exchangeWizardInferenceToken,
   getInferenceBaseUrl,
   looksLikeSeamApiKey,
   type SeamWorkspace,
   type WizardInferenceSession,
 } from './api.js'
+import { describeConnectionFailure } from './connection-error.js'
 import {
   ensureProjectEnvConventions,
   ENV_EXAMPLE_SYMLINK_REFUSAL_MESSAGE,
@@ -649,13 +649,10 @@ export function App({
         )
       } catch (error) {
         if (!cancelled) {
-          const message =
-            error instanceof Error
-              ? error.message
-              : 'Browser connection failed.'
+          const { message, properties } = describeConnectionFailure(error)
           track('wizard_connect_failed', {
             method: 'browser',
-            reason: message,
+            ...properties,
           })
           setPhase({ t: 'error', message })
         }
@@ -665,10 +662,7 @@ export function App({
       if (cancelled) return
       setPhase({
         t: 'error',
-        message:
-          error instanceof Error
-            ? error.message
-            : 'The wizard hit an unexpected error.',
+        message: describeConnectionFailure(error).message,
       })
     })
     return () => {
@@ -695,20 +689,17 @@ export function App({
         )
       } catch (error) {
         if (cancelled) return
-        const message =
-          error instanceof ApiKeyError
-            ? error.message
-            : "Couldn't verify the key."
+        const { message, properties } = describeConnectionFailure(error)
         track('wizard_connect_failed', {
           method: 'paste',
-          reason: message,
+          ...properties,
           attempt: attemptRef.current,
           gave_up: attemptRef.current >= MAX_ATTEMPTS,
         })
         if (attemptRef.current >= MAX_ATTEMPTS) {
           setPhase({
             t: 'error',
-            message: 'Too many attempts. Re-run with a valid key.',
+            message: `Too many attempts. ${message} Re-run the wizard to try again.`,
           })
         } else {
           setPasteError(message)
@@ -721,10 +712,7 @@ export function App({
       if (cancelled) return
       setPhase({
         t: 'error',
-        message:
-          error instanceof Error
-            ? error.message
-            : 'The wizard hit an unexpected error.',
+        message: describeConnectionFailure(error).message,
       })
     })
     return () => {