@cat-factory/app 0.36.0 → 0.37.0

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 },
+      }),
   }
 }