@cat-factory/app 0.35.0 → 0.37.0

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). */

package/app/composables/api/documents.ts

@@ -1,58 +1,64 @@
-import type {
-  DocumentBoardPlan,
-  DocumentConnection,
-  DocumentSearchResult,
-  DocumentSourceDescriptor,
-  DocumentSourceKind,
-  SourceDocument,
-  SpawnResult,
-} from '~/types/domain'
+import {
+  connectDocumentSourceContract,
+  disconnectDocumentSourceContract,
+  importDocumentContract,
+  linkDocumentContract,
+  listDocumentConnectionsContract,
+  listDocumentsContract,
+  listDocumentSourcesContract,
+  planDocumentContract,
+  searchDocumentsContract,
+  spawnDocumentContract,
+} from '@cat-factory/contracts'
+import type { DocumentSourceKind } from '~/types/domain'
 import type { ApiContext } from './context'
 
 /** Document sources (Confluence, Notion, …): connect, import, search, board-spawn. */
-export function documentsApi({ http, ws }: ApiContext) {
+export function documentsApi({ send, ws }: ApiContext) {
   return {
     // ---- document sources (Confluence, Notion, …) -------------------------
     // The configured sources + their connect/import metadata. A 503 means the
     // integration is off (the store hides its UI on any error here).
     listDocumentSources: (workspaceId: string) =>
-      http<{ sources: DocumentSourceDescriptor[] }>(`${ws(workspaceId)}/document-sources`),
+      send(listDocumentSourcesContract, { pathPrefix: ws(workspaceId) }),
 
     listDocumentConnections: (workspaceId: string) =>
-      http<{ connections: DocumentConnection[] }>(
-        `${ws(workspaceId)}/document-sources/connections`,
-      ),
+      send(listDocumentConnectionsContract, { pathPrefix: ws(workspaceId) }),
 
     connectDocumentSource: (
       workspaceId: string,
       source: DocumentSourceKind,
       credentials: Record<string, string>,
     ) =>
-      http<DocumentConnection>(`${ws(workspaceId)}/document-sources/${source}/connect`, {
-        method: 'POST',
+      send(connectDocumentSourceContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { source },
         body: { credentials },
       }),
 
     disconnectDocumentSource: (workspaceId: string, source: DocumentSourceKind) =>
-      http(`${ws(workspaceId)}/document-sources/${source}/connection`, { method: 'DELETE' }),
+      send(disconnectDocumentSourceContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { source },
+      }),
 
-    listDocuments: (workspaceId: string) => http<SourceDocument[]>(`${ws(workspaceId)}/documents`),
+    listDocuments: (workspaceId: string) =>
+      send(listDocumentsContract, { pathPrefix: ws(workspaceId) }),
 
     importDocument: (workspaceId: string, source: DocumentSourceKind, body: { ref: string }) =>
-      http<SourceDocument>(`${ws(workspaceId)}/document-sources/${source}/import`, {
-        method: 'POST',
-        body,
-      }),
+      send(importDocumentContract, { pathPrefix: ws(workspaceId), pathParams: { source }, body }),
 
     searchDocumentSource: (workspaceId: string, source: DocumentSourceKind, query: string) =>
-      http<{ results: DocumentSearchResult[] }>(
-        `${ws(workspaceId)}/document-sources/${source}/search`,
-        { method: 'POST', body: { query } },
-      ),
+      send(searchDocumentsContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { source },
+        body: { query },
+      }),
 
     planDocument: (workspaceId: string, source: DocumentSourceKind, externalId: string) =>
-      http<DocumentBoardPlan>(`${ws(workspaceId)}/document-sources/${source}/plan`, {
-        method: 'POST',
+      send(planDocumentContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { source },
         body: { externalId },
       }),
 
@@ -60,15 +66,11 @@ export function documentsApi({ http, ws }: ApiContext) {
       workspaceId: string,
       source: DocumentSourceKind,
       body: { externalId: string; frameId?: string },
-    ) =>
-      http<{ plan: DocumentBoardPlan; result: SpawnResult }>(
-        `${ws(workspaceId)}/document-sources/${source}/spawn`,
-        { method: 'POST', body },
-      ),
+    ) => send(spawnDocumentContract, { pathPrefix: ws(workspaceId), pathParams: { source }, body }),
 
     linkDocument: (
       workspaceId: string,
       body: { source: DocumentSourceKind; externalId: string; blockId: string },
-    ) => http<SourceDocument>(`${ws(workspaceId)}/documents/link`, { method: 'POST', body }),
+    ) => send(linkDocumentContract, { pathPrefix: ws(workspaceId), body }),
   }
 }

package/app/composables/api/execution.ts

@@ -1,15 +1,24 @@
-import type { Block, ExecutionInstance } from '~/types/domain'
-import type {
-  AgentContextSnapshot,
-  IterationCapChoice,
-  LlmCallMetric,
-  LlmMetricsExport,
-  ReviewComment,
-} from '~/types/execution'
+import {
+  approveStepContract,
+  cancelExecutionContract,
+  exportExecutionLlmMetricsContract,
+  getExecutionAgentContextContract,
+  getExecutionLlmMetricsContract,
+  mergeBlockContract,
+  rejectStepContract,
+  requestStepChangesContract,
+  resolveDecisionContract,
+  resolveStepExceededContract,
+  restartExecutionContract,
+  resumeSpendContract,
+  startExecutionContract,
+} from '@cat-factory/contracts'
+import type { RequestStepChangesInput } from '@cat-factory/contracts'
+import type { IterationCapChoice } from '~/types/execution'
 import type { ApiContext } from './context'
 
 /** Run lifecycle (start/cancel/decisions/approvals/restart) + LLM metrics + spend. */
-export function executionApi({ http, ws, pwHeaders }: ApiContext) {
+export function executionApi({ send, sendWith, ws, pwHeaders }: ApiContext) {
   return {
     // ---- executions -------------------------------------------------------
     startExecution: (
@@ -18,17 +27,17 @@ export function executionApi({ http, ws, pwHeaders }: ApiContext) {
       body: { pipelineId: string },
       password?: string,
     ) =>
-      http<ExecutionInstance>(`${ws(workspaceId)}/blocks/${blockId}/executions`, {
-        method: 'POST',
+      sendWith(pwHeaders(password), startExecutionContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { blockId },
         body,
-        headers: pwHeaders(password),
       }),
 
     cancelExecution: (workspaceId: string, blockId: string) =>
-      http<Block>(`${ws(workspaceId)}/blocks/${blockId}/executions`, { method: 'DELETE' }),
+      send(cancelExecutionContract, { pathPrefix: ws(workspaceId), pathParams: { blockId } }),
 
     mergeBlock: (workspaceId: string, blockId: string) =>
-      http<Block>(`${ws(workspaceId)}/blocks/${blockId}/merge`, { method: 'POST' }),
+      send(mergeBlockContract, { pathPrefix: ws(workspaceId), pathParams: { blockId } }),
 
     resolveDecision: (
       workspaceId: string,
@@ -37,10 +46,11 @@ export function executionApi({ http, ws, pwHeaders }: ApiContext) {
       body: { choice: string },
       password?: string,
     ) =>
-      http<ExecutionInstance>(
-        `${ws(workspaceId)}/executions/${executionId}/decisions/${decisionId}`,
-        { method: 'POST', body, headers: pwHeaders(password) },
-      ),
+      sendWith(pwHeaders(password), resolveDecisionContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId, decisionId },
+        body,
+      }),
 
     approveStep: (
       workspaceId: string,
@@ -49,22 +59,24 @@ export function executionApi({ http, ws, pwHeaders }: ApiContext) {
       body: { proposal?: string },
       password?: string,
     ) =>
-      http<ExecutionInstance>(
-        `${ws(workspaceId)}/executions/${executionId}/steps/${approvalId}/approve`,
-        { method: 'POST', body, headers: pwHeaders(password) },
-      ),
+      sendWith(pwHeaders(password), approveStepContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId, approvalId },
+        body,
+      }),
 
     requestStepChanges: (
       workspaceId: string,
       executionId: string,
       approvalId: string,
-      body: { feedback?: string; comments?: ReviewComment[] },
+      body: RequestStepChangesInput,
       password?: string,
     ) =>
-      http<ExecutionInstance>(
-        `${ws(workspaceId)}/executions/${executionId}/steps/${approvalId}/request-changes`,
-        { method: 'POST', body, headers: pwHeaders(password) },
-      ),
+      sendWith(pwHeaders(password), requestStepChangesContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId, approvalId },
+        body,
+      }),
 
     rejectStep: (
       workspaceId: string,
@@ -72,10 +84,11 @@ export function executionApi({ http, ws, pwHeaders }: ApiContext) {
       approvalId: string,
       body: { reason?: string },
     ) =>
-      http<ExecutionInstance>(
-        `${ws(workspaceId)}/executions/${executionId}/steps/${approvalId}/reject`,
-        { method: 'POST', body },
-      ),
+      send(rejectStepContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId, approvalId },
+        body,
+      }),
 
     // Resolve a companion step parked at its rework cap: one more round / proceed /
     // stop & reset (the companion analogue of resolveRequirementsExceeded).
@@ -86,10 +99,11 @@ export function executionApi({ http, ws, pwHeaders }: ApiContext) {
       body: { choice: IterationCapChoice },
       password?: string,
     ) =>
-      http<ExecutionInstance>(
-        `${ws(workspaceId)}/executions/${executionId}/steps/${approvalId}/resolve-exceeded`,
-        { method: 'POST', body, headers: pwHeaders(password) },
-      ),
+      sendWith(pwHeaders(password), resolveStepExceededContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId, approvalId },
+        body,
+      }),
 
     // Restart a run from a chosen step: re-run from `fromStepIndex` onward (resetting
     // that step + later steps' iteration counters) while keeping the earlier steps'
@@ -101,35 +115,38 @@ export function executionApi({ http, ws, pwHeaders }: ApiContext) {
       fromStepIndex: number,
       password?: string,
     ) =>
-      http<ExecutionInstance>(`${ws(workspaceId)}/executions/${executionId}/restart`, {
-        method: 'POST',
+      sendWith(pwHeaders(password), restartExecutionContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
         body: { fromStepIndex },
-        headers: pwHeaders(password),
       }),
 
     // ---- LLM observability (per-run model-call metrics) -------------------
     // The full per-call detail behind the board's step rollups. Empty when the
     // observability sink is not wired.
     getLlmMetrics: (workspaceId: string, executionId: string) =>
-      http<{ executionId: string; calls: LlmCallMetric[] }>(
-        `${ws(workspaceId)}/executions/${encodeURIComponent(executionId)}/llm-metrics`,
-      ),
+      send(getExecutionLlmMetricsContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
+      }),
 
     // The LLM-friendly export bundle (totals + per-agent insights + every call).
     exportLlmMetrics: (workspaceId: string, executionId: string) =>
-      http<LlmMetricsExport>(
-        `${ws(workspaceId)}/executions/${encodeURIComponent(executionId)}/llm-metrics/export`,
-      ),
+      send(exportExecutionLlmMetricsContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
+      }),
 
     // The complete provided context per container-agent dispatch (composed prompts,
     // folded-in fragments, injected files). Empty when not wired / storing is off.
     getAgentContext: (workspaceId: string, executionId: string) =>
-      http<{ executionId: string; snapshots: AgentContextSnapshot[] }>(
-        `${ws(workspaceId)}/executions/${encodeURIComponent(executionId)}/agent-context`,
-      ),
+      send(getExecutionAgentContextContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId },
+      }),
 
     // ---- spend safeguard --------------------------------------------------
     resumeSpend: (workspaceId: string) =>
-      http<ExecutionInstance[]>(`${ws(workspaceId)}/spend/resume`, { method: 'POST' }),
+      send(resumeSpendContract, { pathPrefix: ws(workspaceId) }),
   }
 }

package/app/composables/api/followUps.ts

@@ -1,4 +1,10 @@
-import type { FollowUpsStepState } from '~/types/execution'
+import {
+  answerFollowUpContract,
+  dismissFollowUpContract,
+  fileFollowUpContract,
+  getFollowUpsContract,
+  queueFollowUpContract,
+} from '@cat-factory/contracts'
 import type { ApiContext } from './context'
 
 /**
@@ -8,45 +14,39 @@ import type { ApiContext } from './context'
  * the last item is decided, the backend drives the run forward (loop the Coder for the
  * queued / answered items, else advance).
  */
-export function followUpsApi({ http, ws }: ApiContext) {
-  const base = (workspaceId: string, executionId: string) =>
-    `${ws(workspaceId)}/executions/${encodeURIComponent(executionId)}/follow-ups`
-
+export function followUpsApi({ send, ws }: ApiContext) {
   return {
     // The live follow-up state for a run (null when the companion is off / nothing surfaced).
     getFollowUps: (workspaceId: string, executionId: string) =>
-      http<FollowUpsStepState | null>(base(workspaceId, executionId)),
+      send(getFollowUpsContract, { pathPrefix: ws(workspaceId), pathParams: { executionId } }),
 
     // File a follow-up as a tracker issue (GitHub Issues / Jira).
     fileFollowUp: (workspaceId: string, executionId: string, itemId: string) =>
-      http<FollowUpsStepState>(
-        `${base(workspaceId, executionId)}/${encodeURIComponent(itemId)}/file`,
-        {
-          method: 'POST',
-        },
-      ),
+      send(fileFollowUpContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId, itemId },
+      }),
 
     // Send a follow-up back to the Coder (queued for its next pass).
     queueFollowUp: (workspaceId: string, executionId: string, itemId: string) =>
-      http<FollowUpsStepState>(
-        `${base(workspaceId, executionId)}/${encodeURIComponent(itemId)}/queue`,
-        {
-          method: 'POST',
-        },
-      ),
+      send(queueFollowUpContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId, itemId },
+      }),
 
     // Answer a question item (folded into the Coder's next pass).
     answerFollowUp: (workspaceId: string, executionId: string, itemId: string, answer: string) =>
-      http<FollowUpsStepState>(
-        `${base(workspaceId, executionId)}/${encodeURIComponent(itemId)}/answer`,
-        { method: 'POST', body: { answer } },
-      ),
+      send(answerFollowUpContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId, itemId },
+        body: { answer },
+      }),
 
     // Dismiss a follow-up / question item without acting on it.
     dismissFollowUp: (workspaceId: string, executionId: string, itemId: string) =>
-      http<FollowUpsStepState>(
-        `${base(workspaceId, executionId)}/${encodeURIComponent(itemId)}/dismiss`,
-        { method: 'POST' },
-      ),
+      send(dismissFollowUpContract, {
+        pathPrefix: ws(workspaceId),
+        pathParams: { executionId, itemId },
+      }),
   }
 }

package/app/composables/api/fragments.ts

@@ -1,34 +1,44 @@
+import {
+  createDocumentFragmentContract,
+  createPromptFragmentContract,
+  deletePromptFragmentContract,
+  fragmentSourceStatusContract,
+  linkFragmentSourceContract,
+  listFragmentCatalogContract,
+  listFragmentSourcesContract,
+  listPromptFragmentsContract,
+  refreshPromptFragmentContract,
+  resolvedFragmentsContract,
+  syncFragmentSourceContract,
+  unlinkFragmentSourceContract,
+  updatePromptFragmentContract,
+} from '@cat-factory/contracts'
 import type {
   CreateDocumentFragmentInput,
   CreatePromptFragmentInput,
   FragmentOwnerKind,
-  FragmentSource,
-  FragmentSourceStatus,
-  FragmentSyncResult,
   LinkFragmentSourceInput,
-  PromptFragment,
-  ResolvedFragment,
   UpdatePromptFragmentInput,
 } from '~/types/domain'
 import type { ApiContext } from './context'
 
 /** Best-practice prompt-fragment catalog + the managed, tenant-scoped library. */
-export function fragmentsApi({ http, ws, scope }: ApiContext) {
+export function fragmentsApi({ send, ws, scope }: ApiContext) {
   return {
     // ---- prompt fragments (best-practice catalog) -------------------------
-    getPromptFragments: () => http<PromptFragment[]>('/prompt-fragments'),
+    getPromptFragments: () => send(listFragmentCatalogContract, {}),
 
     // ---- prompt-fragment library (managed, tenant-scoped; ADR 0006) -------
     // The merged catalog an agent actually sees for a board (builtin∪account∪ws).
     getResolvedFragments: (workspaceId: string) =>
-      http<ResolvedFragment[]>(`${ws(workspaceId)}/prompt-fragments/resolved`),
+      send(resolvedFragmentsContract, { pathPrefix: ws(workspaceId) }),
 
     // Per-tier management (scope = account or workspace).
     listFragments: (kind: FragmentOwnerKind, id: string) =>
-      http<PromptFragment[]>(`${scope(kind, id)}/prompt-fragments`),
+      send(listPromptFragmentsContract, { pathPrefix: scope(kind, id) }),
 
     createFragment: (kind: FragmentOwnerKind, id: string, body: CreatePromptFragmentInput) =>
-      http<PromptFragment>(`${scope(kind, id)}/prompt-fragments`, { method: 'POST', body }),
+      send(createPromptFragmentContract, { pathPrefix: scope(kind, id), body }),
 
     updateFragment: (
       kind: FragmentOwnerKind,
@@ -36,14 +46,16 @@ export function fragmentsApi({ http, ws, scope }: ApiContext) {
       fragmentId: string,
       body: UpdatePromptFragmentInput,
     ) =>
-      http<PromptFragment>(
-        `${scope(kind, id)}/prompt-fragments/${encodeURIComponent(fragmentId)}`,
-        { method: 'PATCH', body },
-      ),
+      send(updatePromptFragmentContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { fragmentId },
+        body,
+      }),
 
     deleteFragment: (kind: FragmentOwnerKind, id: string, fragmentId: string) =>
-      http(`${scope(kind, id)}/prompt-fragments/${encodeURIComponent(fragmentId)}`, {
-        method: 'DELETE',
+      send(deletePromptFragmentContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { fragmentId },
       }),
 
     // Link an external document (Confluence/Notion/GitHub) as a living fragment.
@@ -51,7 +63,7 @@ export function fragmentsApi({ http, ws, scope }: ApiContext) {
       kind: FragmentOwnerKind,
       id: string,
       body: CreateDocumentFragmentInput,
-    ) => http<PromptFragment>(`${scope(kind, id)}/document-fragments`, { method: 'POST', body }),
+    ) => send(createDocumentFragmentContract, { pathPrefix: scope(kind, id), body }),
 
     // Force an immediate live re-resolve of a document-backed fragment. At the
     // account scope the backend needs a `viaWorkspaceId` (the workspace whose
@@ -62,34 +74,35 @@ export function fragmentsApi({ http, ws, scope }: ApiContext) {
       fragmentId: string,
       viaWorkspaceId?: string,
     ) =>
-      http<PromptFragment>(
-        `${scope(kind, id)}/prompt-fragments/${encodeURIComponent(fragmentId)}/refresh${
-          viaWorkspaceId ? `?viaWorkspaceId=${encodeURIComponent(viaWorkspaceId)}` : ''
-        }`,
-        { method: 'POST' },
-      ),
+      send(refreshPromptFragmentContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { fragmentId },
+        queryParams: { viaWorkspaceId },
+      }),
 
     // Repo sources of guideline Markdown.
     listFragmentSources: (kind: FragmentOwnerKind, id: string) =>
-      http<FragmentSource[]>(`${scope(kind, id)}/fragment-sources`),
+      send(listFragmentSourcesContract, { pathPrefix: scope(kind, id) }),
 
     linkFragmentSource: (kind: FragmentOwnerKind, id: string, body: LinkFragmentSourceInput) =>
-      http<FragmentSource>(`${scope(kind, id)}/fragment-sources`, { method: 'POST', body }),
+      send(linkFragmentSourceContract, { pathPrefix: scope(kind, id), body }),
 
     unlinkFragmentSource: (kind: FragmentOwnerKind, id: string, sourceId: string) =>
-      http(`${scope(kind, id)}/fragment-sources/${encodeURIComponent(sourceId)}`, {
-        method: 'DELETE',
+      send(unlinkFragmentSourceContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { id: sourceId },
       }),
 
     fragmentSourceStatus: (kind: FragmentOwnerKind, id: string, sourceId: string) =>
-      http<FragmentSourceStatus>(
-        `${scope(kind, id)}/fragment-sources/${encodeURIComponent(sourceId)}/status`,
-      ),
+      send(fragmentSourceStatusContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { id: sourceId },
+      }),
 
     syncFragmentSource: (kind: FragmentOwnerKind, id: string, sourceId: string) =>
-      http<FragmentSyncResult>(
-        `${scope(kind, id)}/fragment-sources/${encodeURIComponent(sourceId)}/sync`,
-        { method: 'POST' },
-      ),
+      send(syncFragmentSourceContract, {
+        pathPrefix: scope(kind, id),
+        pathParams: { id: sourceId },
+      }),
   }
 }