@cat-factory/app 0.36.0 → 0.37.1

package/app/composables/api/accounts.ts

@@ -1,93 +1,78 @@
-import type {
-  Account,
-  AccountInvitation,
-  AccountMember,
-  AccountRole,
-  AddMemberInput,
-  EmailConnection,
-  UpdateAccountInput,
-} from '~/types/domain'
-import type { AccountSettingsView, UpdateAccountSettingsInput } from '~/types/accountSettings'
+import {
+  addAccountMemberContract,
+  connectEmailContract,
+  createAccountContract,
+  createInvitationContract,
+  disconnectEmailContract,
+  getAccountSettingsContract,
+  getEmailConnectionContract,
+  listAccountMembersContract,
+  listAccountsContract,
+  listInvitationsContract,
+  revokeInvitationContract,
+  setMemberRolesContract,
+  testEmailContract,
+  updateAccountContract,
+  updateAccountSettingsContract,
+} from '@cat-factory/contracts'
+import type { AccountRole, UpdateAccountInput } from '~/types/domain'
+import type { UpdateAccountSettingsInput } from '~/types/accountSettings'
 import type { ApiContext } from './context'
 
 /** Account (tenancy) management: orgs, members, invitations + the email sender. */
-export function accountsApi({ http }: ApiContext) {
+export function accountsApi({ send }: ApiContext) {
   return {
     // ---- accounts (tenancy) -----------------------------------------------
     // The accounts the user can switch between (personal + orgs), org creation
     // and membership management. Empty when auth is disabled (dev).
-    listAccounts: () => http<Account[]>('/accounts'),
+    listAccounts: () => send(listAccountsContract, {}),
 
     createAccount: (body: { name: string; githubAccountLogin?: string }) =>
-      http<Account>('/accounts', { method: 'POST', body }),
+      send(createAccountContract, { body }),
 
     updateAccount: (accountId: string, body: UpdateAccountInput) =>
-      http<Account>(`/accounts/${encodeURIComponent(accountId)}`, { method: 'PATCH', body }),
+      send(updateAccountContract, { pathParams: { accountId }, body }),
 
     listAccountMembers: (accountId: string) =>
-      http<AccountMember[]>(`/accounts/${encodeURIComponent(accountId)}/members`),
+      send(listAccountMembersContract, { pathParams: { accountId } }),
 
-    addAccountMember: (accountId: string, body: AddMemberInput) =>
-      http<AccountMember>(`/accounts/${encodeURIComponent(accountId)}/members`, {
-        method: 'POST',
-        body,
-      }),
+    addAccountMember: (accountId: string, body: { userId: string; roles?: AccountRole[] }) =>
+      send(addAccountMemberContract, { pathParams: { accountId }, body }),
 
     setMemberRoles: (accountId: string, userId: string, roles: AccountRole[]) =>
-      http<AccountMember>(
-        `/accounts/${encodeURIComponent(accountId)}/members/${encodeURIComponent(userId)}/roles`,
-        { method: 'PATCH', body: { roles } },
-      ),
+      send(setMemberRolesContract, { pathParams: { accountId, userId }, body: { roles } }),
 
     // Invitations: invite teammates by email into an org account.
     listInvitations: (accountId: string) =>
-      http<AccountInvitation[]>(`/accounts/${encodeURIComponent(accountId)}/invitations`),
+      send(listInvitationsContract, { pathParams: { accountId } }),
 
     createInvitation: (accountId: string, body: { email: string; roles?: AccountRole[] }) =>
-      http<{ invitation: AccountInvitation; acceptUrl: string | null }>(
-        `/accounts/${encodeURIComponent(accountId)}/invitations`,
-        { method: 'POST', body },
-      ),
+      send(createInvitationContract, { pathParams: { accountId }, body }),
 
     revokeInvitation: (accountId: string, invitationId: string) =>
-      http(
-        `/accounts/${encodeURIComponent(accountId)}/invitations/${encodeURIComponent(invitationId)}`,
-        { method: 'DELETE' },
-      ),
+      send(revokeInvitationContract, { pathParams: { accountId, invitationId } }),
 
     // Per-account email sender (UI-onboarded): connect/inspect/disconnect/test.
     getEmailConnection: (accountId: string) =>
-      http<{ connection: EmailConnection | null; configured: boolean }>(
-        `/accounts/${encodeURIComponent(accountId)}/email-connection`,
-      ),
+      send(getEmailConnectionContract, { pathParams: { accountId } }),
 
     connectEmail: (
       accountId: string,
       body: { provider: 'sendgrid' | 'resend'; apiKey: string; fromAddress: string },
-    ) =>
-      http<EmailConnection>(`/accounts/${encodeURIComponent(accountId)}/email-connection`, {
-        method: 'POST',
-        body,
-      }),
+    ) => send(connectEmailContract, { pathParams: { accountId }, body }),
 
     disconnectEmail: (accountId: string) =>
-      http(`/accounts/${encodeURIComponent(accountId)}/email-connection`, { method: 'DELETE' }),
+      send(disconnectEmailContract, { pathParams: { accountId } }),
 
     testEmail: (accountId: string, to: string) =>
-      http<{ ok: boolean }>(`/accounts/${encodeURIComponent(accountId)}/email-connection/test`, {
-        method: 'POST',
-        body: { to },
-      }),
+      send(testEmailContract, { pathParams: { accountId }, body: { to } }),
 
     // Per-account deployment settings (admin only): integration secrets (Slack OAuth +
     // web-search keys), sealed at rest. Read returns config + non-secret summary only.
     getAccountSettings: (accountId: string) =>
-      http<AccountSettingsView>(`/accounts/${encodeURIComponent(accountId)}/settings`),
+      send(getAccountSettingsContract, { pathParams: { accountId } }),
 
     updateAccountSettings: (accountId: string, body: UpdateAccountSettingsInput) =>
-      http<AccountSettingsView>(`/accounts/${encodeURIComponent(accountId)}/settings`, {
-        method: 'PUT',
-        body,
-      }),
+      send(updateAccountSettingsContract, { pathParams: { accountId }, body }),
   }
 }

package/app/composables/api/auth.ts

@@ -1,42 +1,43 @@
-import type { AuthUser } from '~/types/domain'
+import {
+  acceptInvitationContract,
+  authConfigContract,
+  logoutContract,
+  meContract,
+  passwordLoginContract,
+  peekInvitationContract,
+  signupContract,
+} from '@cat-factory/contracts'
 import type { ApiContext } from './context'
 
 /** Auth/session endpoints + the events-WebSocket ticket mint. */
-export function authApi({ http, ws }: ApiContext) {
+export function authApi({ http, send, ws }: ApiContext) {
   return {
     // ---- auth -------------------------------------------------------------
-    getAuthConfig: () =>
-      http<{
-        enabled: boolean
-        providers?: { github: boolean; password: boolean; google: boolean }
-        /** Local-mode signals; present only when the backend is the local facade. */
-        localMode?: { enabled: boolean; githubPatSetupUrl?: string }
-      }>('/auth/config'),
+    // The `/auth/*` JSON endpoints are mounted under the `/auth` prefix; their
+    // contract paths are relative to it.
+    getAuthConfig: () => send(authConfigContract, { pathPrefix: '/auth' }),
 
-    getMe: () => http<{ user: AuthUser | null; enabled: boolean }>('/auth/me'),
+    getMe: () => send(meContract, { pathPrefix: '/auth' }),
 
     signup: (body: { email: string; password: string; name?: string; invite?: string }) =>
-      http<{ token: string; user: AuthUser }>('/auth/signup', { method: 'POST', body }),
+      send(signupContract, { pathPrefix: '/auth', body }),
 
     passwordLogin: (body: { email: string; password: string }) =>
-      http<{ token: string; user: AuthUser }>('/auth/password-login', { method: 'POST', body }),
+      send(passwordLoginContract, { pathPrefix: '/auth', body }),
 
     peekInvite: (token: string) =>
-      http<{ valid: boolean; email?: string; accountName?: string | null }>(
-        `/auth/invitations/${encodeURIComponent(token)}`,
-      ),
+      send(peekInvitationContract, { pathPrefix: '/auth', pathParams: { token } }),
 
     acceptInvite: (token: string) =>
-      http<{ accountId: string }>(`/auth/invitations/${encodeURIComponent(token)}/accept`, {
-        method: 'POST',
-      }),
+      send(acceptInvitationContract, { pathPrefix: '/auth', pathParams: { token } }),
 
-    logout: () => http('/auth/logout', { method: 'POST' }),
+    logout: () => send(logoutContract, { pathPrefix: '/auth' }),
 
     // Mint a short-lived, workspace-scoped ticket for the events WebSocket. A
     // browser can't set Authorization on a WS handshake, so the socket auths from
     // this `?ticket=` instead of the long-lived session token. Empty string when
     // auth is disabled (dev) — the handshake is open in that case.
+    // No route contract exists for this endpoint, so it stays on the raw `http` client.
     mintEventsTicket: (workspaceId: string) =>
       http<{ ticket: string; expiresInMs?: number }>(`${ws(workspaceId)}/events/ticket`, {
         method: 'POST',

package/app/composables/api/board.ts

@@ -1,34 +1,42 @@
-import type { Block, BlockType, CreateTaskType, Pipeline, TaskTypeFields } from '~/types/domain'
-import type { ConsensusStepConfig, StepGating } from '~/types/consensus'
+import {
+  addEpicContract,
+  addFrameContract,
+  addModuleContract,
+  addServiceFromRepoContract,
+  addTaskContract,
+  assignEpicContract,
+  clonePipelineContract,
+  createPipelineContract,
+  deletePipelineContract,
+  listPipelinesContract,
+  moveBlockContract,
+  organizePipelineContract,
+  removeBlockContract,
+  reparentBlockContract,
+  toggleDependencyContract,
+  updateBlockContract,
+  updatePipelineContract,
+} from '@cat-factory/contracts'
+import type {
+  CreatePipelineInput,
+  UpdateBlockInput,
+  UpdatePipelineInput,
+} from '@cat-factory/contracts'
+import type { BlockType, CreateTaskType, TaskTypeFields } from '~/types/domain'
 import type { ApiContext, Position } from './context'
 
-/**
- * Create/update body for a pipeline. `name`+`agentKinds` required on create, all optional on
- * update; the parallel arrays are aligned to `agentKinds` and persisted only when non-default.
- */
-interface PipelineWriteBody {
-  name?: string
-  agentKinds?: string[]
-  gates?: boolean[]
-  thresholds?: (number | null)[]
-  enabled?: boolean[]
-  consensus?: (ConsensusStepConfig | null)[]
-  gating?: (StepGating | null)[]
-  labels?: string[]
-}
-
 /** Board structure: block (frame/module/task) mutations + the pipeline library. */
-export function boardApi({ http, ws }: ApiContext) {
+export function boardApi({ send, ws }: ApiContext) {
   return {
     // ---- blocks -----------------------------------------------------------
     addFrame: (workspaceId: string, body: { type: BlockType; position: Position }) =>
-      http<Block>(`${ws(workspaceId)}/blocks`, { method: 'POST', body }),
+      send(addFrameContract, { pathPrefix: ws(workspaceId), body }),
 
     // Import an existing GitHub repo as a service frame (no bootstrap run).
     addServiceFromRepo: (
       workspaceId: string,
       body: { repoGithubId: number; position?: Position; directory?: string; isMonorepo?: boolean },
-    ) => http<Block>(`${ws(workspaceId)}/blocks/from-repo`, { method: 'POST', body }),
+    ) => send(addServiceFromRepoContract, { pathPrefix: ws(workspaceId), body }),
 
     addTask: (
       workspaceId: string,
@@ -44,54 +52,65 @@ export function boardApi({ http, ws }: ApiContext) {
         agentConfig?: Record<string, string>
         technical?: boolean
       },
-    ) => http<Block>(`${ws(workspaceId)}/blocks/${blockId}/tasks`, { method: 'POST', body }),
+    ) => send(addTaskContract, { pathPrefix: ws(workspaceId), pathParams: { blockId }, body }),
 
     addModule: (
       workspaceId: string,
       blockId: string,
       body: { name: string; position?: Position },
-    ) => http<Block>(`${ws(workspaceId)}/blocks/${blockId}/modules`, { method: 'POST', body }),
+    ) => send(addModuleContract, { pathPrefix: ws(workspaceId), pathParams: { blockId }, body }),
 
     // Create an epic grouping node (optionally placed under a service/module).
     addEpic: (
       workspaceId: string,
       body: { title: string; description?: string; position: Position; parentId?: string },
-    ) => http<Block>(`${ws(workspaceId)}/epics`, { method: 'POST', body }),
+    ) => send(addEpicContract, { pathPrefix: ws(workspaceId), body }),
 
     // Assign a task to an epic, or detach it (epicId: null).
     assignToEpic: (workspaceId: string, blockId: string, body: { epicId: string | null }) =>
-      http<Block>(`${ws(workspaceId)}/blocks/${blockId}/epic`, { method: 'POST', body }),
+      send(assignEpicContract, { pathPrefix: ws(workspaceId), pathParams: { blockId }, body }),
 
-    updateBlock: (workspaceId: string, blockId: string, body: Partial<Block>) =>
-      http<Block>(`${ws(workspaceId)}/blocks/${blockId}`, { method: 'PATCH', body }),
+    updateBlock: (workspaceId: string, blockId: string, body: UpdateBlockInput) =>
+      send(updateBlockContract, { pathPrefix: ws(workspaceId), pathParams: { blockId }, body }),
 
     moveBlock: (workspaceId: string, blockId: string, body: { position: Position }) =>
-      http<Block>(`${ws(workspaceId)}/blocks/${blockId}/move`, { method: 'POST', body }),
+      send(moveBlockContract, { pathPrefix: ws(workspaceId), pathParams: { blockId }, body }),
 
     reparentBlock: (
       workspaceId: string,
       blockId: string,
       body: { parentId: string; position: Position },
-    ) => http<Block>(`${ws(workspaceId)}/blocks/${blockId}/reparent`, { method: 'POST', body }),
+    ) =>
+      send(reparentBlockContract, { pathPrefix: ws(workspaceId), pathParams: { blockId }, body }),
 
     removeBlock: (workspaceId: string, blockId: string) =>
-      http(`${ws(workspaceId)}/blocks/${blockId}`, { method: 'DELETE' }),
+      send(removeBlockContract, { pathPrefix: ws(workspaceId), pathParams: { blockId } }),
 
     toggleDependency: (workspaceId: string, blockId: string, body: { sourceId: string }) =>
-      http<Block>(`${ws(workspaceId)}/blocks/${blockId}/dependencies`, { method: 'POST', body }),
+      send(toggleDependencyContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { blockId },
+        body,
+      }),
 
     // ---- pipelines --------------------------------------------------------
-    listPipelines: (workspaceId: string) => http<Pipeline[]>(`${ws(workspaceId)}/pipelines`),
+    listPipelines: (workspaceId: string) =>
+      send(listPipelinesContract, { pathPrefix: ws(workspaceId) }),
 
-    createPipeline: (workspaceId: string, body: PipelineWriteBody) =>
-      http<Pipeline>(`${ws(workspaceId)}/pipelines`, { method: 'POST', body }),
+    createPipeline: (workspaceId: string, body: CreatePipelineInput) =>
+      send(createPipelineContract, { pathPrefix: ws(workspaceId), body }),
 
-    updatePipeline: (workspaceId: string, pipelineId: string, body: PipelineWriteBody) =>
-      http<Pipeline>(`${ws(workspaceId)}/pipelines/${pipelineId}`, { method: 'PATCH', body }),
+    updatePipeline: (workspaceId: string, pipelineId: string, body: UpdatePipelineInput) =>
+      send(updatePipelineContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { pipelineId },
+        body,
+      }),
 
     clonePipeline: (workspaceId: string, pipelineId: string, body: { name?: string } = {}) =>
-      http<Pipeline>(`${ws(workspaceId)}/pipelines/${pipelineId}/clone`, {
-        method: 'POST',
+      send(clonePipelineContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { pipelineId },
         body,
       }),
 
@@ -102,12 +121,13 @@ export function boardApi({ http, ws }: ApiContext) {
       pipelineId: string,
       body: { labels?: string[]; archived?: boolean },
     ) =>
-      http<Pipeline>(`${ws(workspaceId)}/pipelines/${pipelineId}/organize`, {
-        method: 'PATCH',
+      send(organizePipelineContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { pipelineId },
         body,
       }),
 
     removePipeline: (workspaceId: string, pipelineId: string) =>
-      http(`${ws(workspaceId)}/pipelines/${pipelineId}`, { method: 'DELETE' }),
+      send(deletePipelineContract, { pathPrefix: ws(workspaceId), pathParams: { pipelineId } }),
   }
 }

package/app/composables/api/bootstrap.ts

@@ -1,10 +1,15 @@
+import {
+  createReferenceArchitectureContract,
+  deleteReferenceArchitectureContract,
+  listReferenceArchitecturesContract,
+  retryAgentRunContract,
+  startBootstrapJobContract,
+  stopAgentRunContract,
+  updateReferenceArchitectureContract,
+} from '@cat-factory/contracts'
 import type {
-  AgentRunKind,
-  BootstrapJob,
   BootstrapRepoInput,
   CreateReferenceArchitectureInput,
-  ExecutionInstance,
-  ReferenceArchitecture,
   UpdateReferenceArchitectureInput,
 } from '~/types/domain'
 import type { ApiContext } from './context'
@@ -13,50 +18,48 @@ import type { ApiContext } from './context'
  * Repo bootstrap (reference architectures + bootstrap jobs) and the unified
  * agent-run failure/retry/stop surface shared by bootstrap + execution runs.
  */
-export function bootstrapApi({ http, ws, pwHeaders }: ApiContext) {
+export function bootstrapApi({ send, sendWith, ws, pwHeaders }: ApiContext) {
   return {
     // ---- repo bootstrap ---------------------------------------------------
     listReferenceArchitectures: (workspaceId: string) =>
-      http<ReferenceArchitecture[]>(`${ws(workspaceId)}/bootstrap/reference-architectures`),
+      send(listReferenceArchitecturesContract, { pathPrefix: ws(workspaceId) }),
 
     createReferenceArchitecture: (workspaceId: string, body: CreateReferenceArchitectureInput) =>
-      http<ReferenceArchitecture>(`${ws(workspaceId)}/bootstrap/reference-architectures`, {
-        method: 'POST',
-        body,
-      }),
+      send(createReferenceArchitectureContract, { pathPrefix: ws(workspaceId), body }),
 
     updateReferenceArchitecture: (
       workspaceId: string,
       id: string,
       body: UpdateReferenceArchitectureInput,
     ) =>
-      http<ReferenceArchitecture>(`${ws(workspaceId)}/bootstrap/reference-architectures/${id}`, {
-        method: 'PATCH',
+      send(updateReferenceArchitectureContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { id },
         body,
       }),
 
     deleteReferenceArchitecture: (workspaceId: string, id: string) =>
-      http(`${ws(workspaceId)}/bootstrap/reference-architectures/${id}`, { method: 'DELETE' }),
+      send(deleteReferenceArchitectureContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { id },
+      }),
 
     bootstrapRepo: (workspaceId: string, body: BootstrapRepoInput) =>
-      http<BootstrapJob>(`${ws(workspaceId)}/bootstrap/jobs`, { method: 'POST', body }),
+      send(startBootstrapJobContract, { pathPrefix: ws(workspaceId), body }),
 
     // ---- agent runs (unified failure + retry) -----------------------------
     // Retry any failed run (bootstrap or execution); the backend resolves the
     // kind from the unified `agent_runs` table and re-drives the right flow.
     retryAgentRun: (workspaceId: string, runId: string, password?: string) =>
-      http<{ kind: AgentRunKind; run: ExecutionInstance | BootstrapJob }>(
-        `${ws(workspaceId)}/agent-runs/${encodeURIComponent(runId)}/retry`,
-        { method: 'POST', headers: pwHeaders(password) },
-      ),
+      sendWith(pwHeaders(password), retryAgentRunContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { id: runId },
+      }),
 
     // Explicitly stop a running run (bootstrap or execution): the backend kills the
     // per-run container and tears down the durable driver, then marks the run
     // terminally cancelled so the board stops showing it as running.
     stopAgentRun: (workspaceId: string, runId: string) =>
-      http<{ kind: AgentRunKind; run: ExecutionInstance | BootstrapJob }>(
-        `${ws(workspaceId)}/agent-runs/${encodeURIComponent(runId)}/stop`,
-        { method: 'POST' },
-      ),
+      send(stopAgentRunContract, { pathPrefix: ws(workspaceId), pathParams: { id: runId } }),
   }
 }

package/app/composables/api/client.ts

@@ -0,0 +1,102 @@
+import type {
+  ApiContract,
+  ClientRequestParams,
+  DefaultStreaming,
+  InferNonSseClientResponse,
+  SuccessfulHttpStatusCode,
+} from '@toad-contracts/core'
+import {
+  type ContractRequestOptions,
+  sendByApiContract,
+  type WretchInstance,
+} from '@toad-contracts/frontend-http-client'
+import wretch from 'wretch'
+
+/**
+ * The validated success-response body inferred from a route contract (every REST
+ * endpoint here is non-SSE). This is what {@link ApiSend} resolves to.
+ */
+export type SuccessBodyOf<T extends ApiContract> = Extract<
+  InferNonSseClientResponse<T>,
+  { statusCode: SuccessfulHttpStatusCode }
+>['body']
+
+/** The request params a contract requires (pathParams/body/queryParams/headers), per the contract. */
+export type SendParams<T extends ApiContract> = ClientRequestParams<
+  T,
+  DefaultStreaming<T['responsesByStatusCode']>
+> &
+  ContractRequestOptions<true>
+
+/**
+ * A bound, throw-on-error sender: validates the response against the contract and
+ * returns the success body, or throws the typed error (an `UnexpectedResponseError`
+ * or a declared non-2xx response). Preserves the throwing ergonomics the Pinia
+ * stores already expect from the old `$fetch` client.
+ */
+export type ApiSend = <T extends ApiContract>(
+  contract: T,
+  params: SendParams<T>,
+) => Promise<SuccessBodyOf<T>>
+
+/**
+ * Build the authed wretch client. Ports the concerns the old `$fetch` client had:
+ * base URL from runtime config, a lazily-read bearer token (so a fresh token applies
+ * without rebuilding the client), and a 401 → re-gate.
+ */
+export function createApiClient(): WretchInstance {
+  const apiBase = useRuntimeConfig().public.apiBase
+  return wretch(apiBase).middlewares([
+    (next) => async (url, opts) => {
+      const token = useAuthStore().token
+      if (token) {
+        opts.headers = {
+          ...(opts.headers as Record<string, string> | undefined),
+          Authorization: `Bearer ${token}`,
+        }
+      }
+      const response = await next(url, opts)
+      // A 401 means our token lapsed or was revoked — drop it so the UI re-gates.
+      if (response.status === 401) useAuthStore().handleUnauthorized()
+      return response
+    },
+  ])
+}
+
+/**
+ * Send a contract request and unwrap to the success body (or throw the typed error).
+ * The public signature preserves per-contract inference for callers; inside,
+ * sendByApiContract's deeply-conditional result type can't be proven equal to
+ * SuccessBodyOf<T> generically, so the success body is asserted at this single boundary.
+ */
+export async function sendContract<T extends ApiContract>(
+  client: WretchInstance,
+  contract: T,
+  params: SendParams<T>,
+): Promise<SuccessBodyOf<T>> {
+  const outcome = await sendByApiContract(client, contract, params)
+  if (outcome.error) throw outcome.error
+  return outcome.result!.body as SuccessBodyOf<T>
+}
+
+/** Curry {@link sendContract} over a client into the throw-on-error {@link ApiSend}. */
+export function createSend(client: WretchInstance): ApiSend {
+  return (contract, params) => sendContract(client, contract, params)
+}
+
+/**
+ * Like {@link ApiSend} but augments the request with ambient headers not modelled by the
+ * contract (the personal-subscription unlock password, mirroring how the bearer token
+ * rides outside the wire body). `undefined` headers send unchanged.
+ */
+export type ApiSendWith = <T extends ApiContract>(
+  extraHeaders: Record<string, string> | undefined,
+  contract: T,
+  params: SendParams<T>,
+) => Promise<SuccessBodyOf<T>>
+
+/** Curry {@link sendContract} with per-call ambient headers (see {@link ApiSendWith}). */
+export function createSendWith(client: WretchInstance): ApiSendWith {
+  return (extraHeaders, contract, params) =>
+    sendContract(extraHeaders ? client.headers(extraHeaders) : client, contract, params)
+}

package/app/composables/api/context.ts

@@ -1,19 +1,38 @@
+import type { WretchInstance } from '@toad-contracts/frontend-http-client'
 import type { FragmentOwnerKind } from '~/types/domain'
+import type { ApiSend, ApiSendWith } from './client'
 
 /** The authed `$fetch` instance type — Nuxt's augmented client, as returned by `$fetch.create`. */
 export type ApiHttp = ReturnType<typeof $fetch.create>
 
 /**
  * Shared plumbing handed to every grouped API module. `useApi()` builds one of
- * these (the authed `$fetch` client + the path/header helpers) and passes it to
- * each `*Api(ctx)` factory; the factories return the endpoint methods that
- * `useApi()` spreads into its single flat client object. Splitting the client
- * this way keeps call sites unchanged (`useApi().someMethod(...)`) while the
- * ~100 endpoints live in cohesive per-domain files.
+ * these (the authed wretch client, the contract `send` helper + the path/header
+ * helpers) and passes it to each `*Api(ctx)` factory; the factories return the
+ * endpoint methods that `useApi()` spreads into its single flat client object.
+ * Splitting the client this way keeps call sites unchanged
+ * (`useApi().someMethod(...)`) while the ~100 endpoints live in cohesive
+ * per-domain files.
  */
 export interface ApiContext {
-  /** The authed `$fetch` instance (bearer token + 401 handling pre-wired). */
+  /**
+   * The authed `$fetch` instance (bearer token + 401 handling pre-wired).
+   * Transitional: API groups not yet migrated to contract `send` still use it.
+   */
   http: ApiHttp
+  /** The authed wretch client (bearer token + 401 handling pre-wired). */
+  client: WretchInstance
+  /**
+   * Contract sender: validates the response against the route contract and returns
+   * the success body, or throws the typed error. The single source of truth for
+   * path + method + request + response is the contract in `@cat-factory/contracts`.
+   */
+  send: ApiSend
+  /**
+   * Like {@link send} but attaches ambient headers the contract doesn't model — today the
+   * personal-subscription unlock password on gated run calls (individual-usage vendors).
+   */
+  sendWith: ApiSendWith
   /** `/workspaces/:id` path prefix (id encoded). */
   ws: (workspaceId: string) => string
   /** Prompt-fragment library prefix, resolved from the owner scope (ADR 0006 §8). */