@cat-factory/app 0.37.1 → 0.37.2

package/app/components/auth/LoginScreen.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { computed, ref } from 'vue'
+import { apiErrorEnvelope } from '~/composables/api/errors'
 
 const auth = useAuthStore()
 
@@ -37,8 +38,7 @@ async function submitPassword() {
     if (typeof window !== 'undefined') window.location.assign(window.location.pathname)
   } catch (e) {
     error.value =
-      (e as { data?: { error?: { message?: string } } })?.data?.error?.message ??
-      'Sign-in failed. Check your details and try again.'
+      apiErrorEnvelope(e)?.message ?? 'Sign-in failed. Check your details and try again.'
   } finally {
     busy.value = false
   }

package/app/components/layout/AccountTeamSettings.vue

@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { computed, onMounted, ref, watch } from 'vue'
+import { apiErrorEnvelope } from '~/composables/api/errors'
 import type { AccountRole } from '~/types/domain'
 import AccountDeploymentSettings from '~/components/layout/AccountDeploymentSettings.vue'
 
@@ -39,9 +40,7 @@ async function updateMemberRoles(userId: string, roles: AccountRole[]) {
 function notifyError(title: string, e: unknown) {
   toast.add({
     title,
-    description:
-      (e as { data?: { error?: { message?: string } } })?.data?.error?.message ??
-      (e instanceof Error ? e.message : String(e)),
+    description: apiErrorEnvelope(e)?.message ?? (e instanceof Error ? e.message : String(e)),
     icon: 'i-lucide-triangle-alert',
     color: 'error',
   })

package/app/composables/api/client.ts

@@ -11,6 +11,7 @@ import {
   type WretchInstance,
 } from '@toad-contracts/frontend-http-client'
 import wretch from 'wretch'
+import { ApiError } from './errors'
 
 /**
  * The validated success-response body inferred from a route contract (every REST
@@ -75,7 +76,16 @@ export async function sendContract<T extends ApiContract>(
   params: SendParams<T>,
 ): Promise<SuccessBodyOf<T>> {
   const outcome = await sendByApiContract(client, contract, params)
-  if (outcome.error) throw outcome.error
+  if (outcome.error) {
+    const error = outcome.error
+    // A contract-declared non-2xx is reported as a plain `{ statusCode, headers, body }`
+    // value (not an Error). Wrap it so call sites get `instanceof Error` + the server's
+    // message; anything already an Error (UnexpectedResponseError, request-validation
+    // SchemaValidationError, a network fault) is rethrown unchanged.
+    if (error instanceof Error) throw error
+    const { statusCode, body } = error as { statusCode: number; body: unknown }
+    throw new ApiError(statusCode, body)
+  }
   return outcome.result!.body as SuccessBodyOf<T>
 }
 

package/app/composables/api/errors.spec.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from 'vitest'
+import { ApiError, apiErrorEnvelope, apiErrorStatus } from '~/composables/api/errors'
+
+// The contract client (`sendByApiContract`) reports a declared non-2xx as a plain
+// `{ statusCode, headers, body }` value — body under `.body`, NOT an Error. Before the
+// `ApiError` wrap, every `instanceof Error` check rendered "[object Object]" and every
+// `.data.error` reader (parseConflict / parseCredentialError / login + probe messages)
+// silently returned nothing. These tests lock that in.
+
+describe('ApiError', () => {
+  const body = { error: { code: 'conflict', message: 'Nope', details: { reason: 'task_limit' } } }
+
+  it('is a real Error carrying the server message, status, and body', () => {
+    const e = new ApiError(409, body)
+    expect(e).toBeInstanceOf(Error)
+    expect(e.message).toBe('Nope') // not "[object Object]"
+    expect(e.statusCode).toBe(409)
+    expect(e.envelope).toEqual(body.error)
+  })
+
+  it('falls back to a status message when the body carries no envelope', () => {
+    expect(new ApiError(500, 'gateway down').message).toBe('Request failed (HTTP 500)')
+  })
+})
+
+describe('apiErrorEnvelope', () => {
+  const envelope = { code: 'credential_required', message: 'Unlock', details: { vendor: 'claude' } }
+
+  it('reads the envelope from a wrapped ApiError (contract client)', () => {
+    expect(apiErrorEnvelope(new ApiError(428, { error: envelope }))).toEqual(envelope)
+  })
+
+  it('reads the envelope from a bare { body } value (contract client, unwrapped)', () => {
+    expect(apiErrorEnvelope({ statusCode: 428, body: { error: envelope } })).toEqual(envelope)
+  })
+
+  it('reads the envelope from a legacy $fetch FetchError (body under .data)', () => {
+    expect(apiErrorEnvelope({ statusCode: 428, data: { error: envelope } })).toEqual(envelope)
+  })
+
+  it('returns undefined for a network/non-API error', () => {
+    expect(apiErrorEnvelope(new Error('socket hang up'))).toBeUndefined()
+    expect(apiErrorEnvelope(undefined)).toBeUndefined()
+  })
+})
+
+describe('apiErrorStatus', () => {
+  it('reads .statusCode (contract client) and .status (legacy)', () => {
+    expect(apiErrorStatus(new ApiError(503, {}))).toBe(503)
+    expect(apiErrorStatus({ status: 500 })).toBe(500)
+    expect(apiErrorStatus(new Error('x'))).toBeUndefined()
+  })
+})

package/app/composables/api/errors.ts

@@ -0,0 +1,63 @@
+/**
+ * A failed API call, normalised to a real `Error`.
+ *
+ * The contract client (`sendByApiContract`) reports a contract-declared non-2xx as a
+ * plain `{ statusCode, headers, body }` value — NOT an `Error` — with the parsed
+ * `{ error: { code, message, details } }` envelope under `body`. Throwing that bare
+ * object breaks every `error instanceof Error` check (they fall to `String(error)` =
+ * `"[object Object]"`) and hides the server's message. `sendContract` wraps it in this
+ * class so call sites get `instanceof Error`, a real `.message` (the server's), the
+ * `.statusCode`, and the typed `.envelope`.
+ */
+export class ApiError extends Error {
+  readonly statusCode: number
+  /** The parsed response body (the `{ error: {...} }` envelope for our controllers). */
+  readonly body: unknown
+
+  constructor(statusCode: number, body: unknown) {
+    super(envelopeOf(body)?.message ?? `Request failed (HTTP ${statusCode})`)
+    this.name = 'ApiError'
+    this.statusCode = statusCode
+    this.body = body
+  }
+
+  /** The `{ code, message, details, issues }` envelope, when the body carries one. */
+  get envelope(): ApiErrorEnvelope | undefined {
+    return envelopeOf(this.body)
+  }
+}
+
+/** The error envelope every controller emits (`handleError` / contract request-validator). */
+export interface ApiErrorEnvelope {
+  code?: string
+  message?: string
+  details?: unknown
+  issues?: { path?: string; message: string }[]
+}
+
+/** Read the `{ error: {...} }` envelope out of a parsed response body, else undefined. */
+function envelopeOf(body: unknown): ApiErrorEnvelope | undefined {
+  if (!body || typeof body !== 'object') return undefined
+  const error = (body as { error?: unknown }).error
+  return error && typeof error === 'object' ? (error as ApiErrorEnvelope) : undefined
+}
+
+/**
+ * Pull the server error envelope out of any thrown API error, regardless of which client
+ * produced it: the contract client (`ApiError`, body under `.body`) or the legacy `$fetch`
+ * path (ofetch `FetchError`, body under `.data`). Returns undefined for network faults or
+ * non-API errors.
+ */
+export function apiErrorEnvelope(error: unknown): ApiErrorEnvelope | undefined {
+  if (error instanceof ApiError) return error.envelope
+  const e = error as { body?: unknown; data?: unknown }
+  return envelopeOf(e?.body) ?? envelopeOf(e?.data)
+}
+
+/** The HTTP status of a thrown API error, when present (contract client or `$fetch`). */
+export function apiErrorStatus(error: unknown): number | undefined {
+  const e = error as { statusCode?: unknown; status?: unknown }
+  if (typeof e?.statusCode === 'number') return e.statusCode
+  if (typeof e?.status === 'number') return e.status
+  return undefined
+}

package/app/composables/usePipelineErrorToast.ts

@@ -6,6 +6,8 @@
  * SAME guidance + "Configure AI" jump as the no-AI-provider startup banner.
  */
 
+import { apiErrorEnvelope } from './api/errors'
+
 /** The parsed shape of a backend conflict (`{ error: { code: 'conflict', details } }`). */
 interface ConflictDetails {
   reason?: string
@@ -13,15 +15,13 @@ interface ConflictDetails {
   [key: string]: unknown
 }
 
-/** Pull a 409 conflict's `{ reason, message, details }` out of a thrown fetch error, else null. */
+/** Pull a 409 conflict's `{ reason, message, details }` out of a thrown API error, else null. */
 export function parseConflict(
   error: unknown,
 ): { reason?: string; message: string; details: ConflictDetails } | null {
-  const body = (
-    error as { data?: { error?: { code?: string; message?: string; details?: ConflictDetails } } }
-  )?.data?.error
+  const body = apiErrorEnvelope(error)
   if (body?.code !== 'conflict') return null
-  const details = body.details ?? {}
+  const details = (body.details as ConflictDetails | undefined) ?? {}
   return {
     reason: typeof details.reason === 'string' ? details.reason : undefined,
     message: body.message ?? 'This action conflicts with the current state.',

package/app/composables/useSourceIntegration.ts

@@ -1,4 +1,5 @@
 import { type ComputedRef, type Ref, computed, ref } from 'vue'
+import { apiErrorEnvelope, apiErrorStatus } from '~/composables/api/errors'
 import { useUpsertList } from '~/composables/useUpsertList'
 
 /**
@@ -79,10 +80,9 @@ export function useSourceIntegration<
       // reason so a panel can explain it (503 = off here; 500 = the backend errored, e.g. an
       // unapplied migration).
       available.value = false
-      const err = e as { statusCode?: number; data?: { error?: { message?: string } } }
-      const serverMessage = err?.data?.error?.message
+      const serverMessage = apiErrorEnvelope(e)?.message
       probeError.value = {
-        status: err?.statusCode ?? null,
+        status: apiErrorStatus(e) ?? null,
         message: serverMessage || (e instanceof Error ? e.message : String(e)),
       }
       sources.value = []

package/app/stores/personalSubscriptions.ts

@@ -1,5 +1,6 @@
 import { defineStore } from 'pinia'
 import { computed, ref } from 'vue'
+import { apiErrorEnvelope } from '~/composables/api/errors'
 import type {
   PersonalSubscriptionStatus,
   StorePersonalSubscriptionInput,
@@ -45,7 +46,7 @@ export interface PendingCredential {
 export function parseCredentialError(
   error: unknown,
 ): { vendor: SubscriptionVendor; reason: PendingCredential['reason'] } | null {
-  const data = (error as { data?: { error?: { code?: string; details?: unknown } } })?.data?.error
+  const data = apiErrorEnvelope(error)
   if (data?.code !== 'credential_required') return null
   const details = data.details as {
     vendor?: SubscriptionVendor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/app",
-  "version": "0.37.1",
+  "version": "0.37.2",
   "description": "Reusable Nuxt layer for the Agent Architecture Board SPA (components, stores, composables, pages). Consume it from a thin deployment app via `extends: ['@cat-factory/app']` and point it at your backend with NUXT_PUBLIC_API_BASE. See deploy/frontend for an example.",
   "repository": {
     "type": "git",
@@ -32,7 +32,7 @@
     "pinia-plugin-persistedstate": "^4.7.1",
     "vue": "^3.5.38",
     "wretch": "^3.0.9",
-    "@cat-factory/contracts": "0.35.0"
+    "@cat-factory/contracts": "0.36.0"
   },
   "devDependencies": {
     "@toad-contracts/testing": "0.3.1",