@cavi-ai/api-client 0.1.0

package/src/extensions/cavi/contracts/surfaces.ts

@@ -0,0 +1,567 @@
+import type { GatewayMode, SurfaceContract } from "../../../contracts/surfaces.js";
+
+export type { GatewayMode, SurfaceContract };
+
+const p = (params: Record<string, string> | undefined, k: string): string => {
+  const v = params?.[k];
+  if (!v) throw new Error(`CAVI_SURFACE_CONTRACTS: missing path param "${k}"`);
+  return encodeURIComponent(v);
+};
+
+export const CAVI_SURFACE_CONTRACTS: Record<string, SurfaceContract> = {
+  "library.fleetStatus": {
+    key: "library.fleetStatus",
+    method: "GET",
+    legacyPath: () => "/library/api/fleet-status",
+    canonicalPath: () => "/api/plugins/library/fleet-status",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/library",
+    note: "Fleet library status extension endpoint.",
+  },
+  "library.status": {
+    key: "library.status",
+    method: "GET",
+    legacyPath: () => "/library/api/status",
+    canonicalPath: () => "/api/plugins/library/status",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/library",
+    note: "Library ingest pipeline counters.",
+  },
+  "library.inbox": {
+    key: "library.inbox",
+    method: "GET",
+    legacyPath: () => "/library/api/inbox",
+    canonicalPath: () => "/api/plugins/library/inbox",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/library",
+    note: "Library inbox endpoint.",
+  },
+  "library.promotable": {
+    key: "library.promotable",
+    method: "GET",
+    legacyPath: () => "/library/api/promotable",
+    canonicalPath: () => "/api/plugins/library/promotable",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/library",
+    note: "Promotable library rows.",
+  },
+  "library.reviewRequests": {
+    key: "library.reviewRequests",
+    method: "GET",
+    legacyPath: () => "/library/api/review-requests",
+    canonicalPath: () => "/api/plugins/library/review-requests",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/library",
+    note: "Library review-request rows.",
+  },
+  "library.search": {
+    key: "library.search",
+    method: "GET",
+    legacyPath: () => "/library/api/search",
+    canonicalPath: () => "/api/plugins/library/search",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/library",
+    note: "Library search endpoint.",
+  },
+  "library.clip": {
+    key: "library.clip",
+    method: "POST",
+    legacyPath: () => "/library/api/clip",
+    canonicalPath: () => "/api/plugins/library/clip",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/library",
+    note: "CaviClip ingest endpoint (URL/text/manual-file capture into the library intake).",
+  },
+  "portal.dashboard": {
+    key: "portal.dashboard",
+    method: "GET",
+    legacyPath: (params) => `/${p(params, "portal")}/api/dashboard`,
+    canonicalPath: (params) => `/api/plugins/portal/${p(params, "portal")}/dashboard`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal",
+    note: "Portal dashboard aggregate.",
+  },
+  "portal.config": {
+    key: "portal.config",
+    method: "POST",
+    legacyPath: (params) => `/${p(params, "portal")}/api/config`,
+    canonicalPath: (params) => `/api/plugins/portal/${p(params, "portal")}/config`,
+    classification: "blocked",
+    degradation: "hard",
+    owner: "extensions/cavi/portal",
+    note: "Portal config patch endpoint.",
+  },
+  "cavi.costHistory": {
+    key: "cavi.costHistory",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/cost/history",
+    canonicalPath: () => "/api/plugins/cavi-control/cost/history",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi",
+    note: "CAVI cost history extension endpoint.",
+  },
+  "cavi.projectBoard.root": {
+    key: "cavi.projectBoard.root",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/deb",
+    canonicalPath: () => "/api/plugins/cavi-control/deb",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/project-board",
+    note: "Project Board aggregate endpoint.",
+  },
+  "cavi.projectBoard.profile": {
+    key: "cavi.projectBoard.profile",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/deb/profile",
+    canonicalPath: () => "/api/plugins/cavi-control/deb/profile",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/project-board",
+    note: "Project Board profile endpoint.",
+  },
+  "cavi.projectBoard.sprint": {
+    key: "cavi.projectBoard.sprint",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/deb/sprint",
+    canonicalPath: () => "/api/plugins/cavi-control/deb/sprint",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/project-board",
+    note: "Project Board sprint endpoint.",
+  },
+  "cavi.projectBoard.backlog": {
+    key: "cavi.projectBoard.backlog",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/deb/backlog",
+    canonicalPath: () => "/api/plugins/cavi-control/deb/backlog",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/project-board",
+    note: "Project Board backlog endpoint.",
+  },
+  "cavi.projectBoard.call": {
+    key: "cavi.projectBoard.call",
+    method: "POST",
+    legacyPath: () => "/cavi-control/api/deb/call",
+    canonicalPath: () => "/api/plugins/cavi-control/deb/call",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/project-board",
+    note: "Project Board command endpoint.",
+  },
+  "cavi.operator.status": {
+    key: "cavi.operator.status",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/operator/status",
+    canonicalPath: () => "/api/plugins/cavi-control/operator/status",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/operator-control",
+    note: "Operator status endpoint.",
+  },
+  "cavi.operator.snapshot": {
+    key: "cavi.operator.snapshot",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/operator/snapshot",
+    canonicalPath: () => "/api/plugins/cavi-control/operator/snapshot",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/operator-control",
+    note: "Operator aggregate snapshot endpoint.",
+  },
+  "cavi.operator.tasks": {
+    key: "cavi.operator.tasks",
+    method: "POST",
+    legacyPath: () => "/cavi-control/api/operator/tasks",
+    canonicalPath: () => "/api/plugins/kanban/tasks",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/operator-control",
+    note: "Operator task create mapped to Kanban task creation.",
+  },
+  "cavi.operator.task": {
+    key: "cavi.operator.task",
+    method: "GET",
+    legacyPath: (params) => `/cavi-control/api/operator/tasks/${p(params, "taskId")}`,
+    canonicalPath: (params) =>
+      `/api/plugins/cavi-control/operator/tasks/${p(params, "taskId")}`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/operator-control",
+    note: "Operator task detail endpoint.",
+  },
+  "cavi.operator.taskDiscourse": {
+    key: "cavi.operator.taskDiscourse",
+    method: "GET",
+    legacyPath: (params) =>
+      `/cavi-control/api/operator/tasks/${p(params, "taskId")}/discourse`,
+    canonicalPath: (params) =>
+      `/api/plugins/cavi-control/operator/tasks/${p(params, "taskId")}/discourse`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/discourse",
+    note: "Operator task discourse endpoint.",
+  },
+  "cavi.operator.registry": {
+    key: "cavi.operator.registry",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/operator/registry",
+    canonicalPath: () => "/api/plugins/cavi-control/operator/registry",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/operator-control",
+    note: "Operator registry endpoint.",
+  },
+  "cavi.operator.memory": {
+    key: "cavi.operator.memory",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/operator/memory",
+    canonicalPath: () => "/api/plugins/cavi-control/operator/memory",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/operator-control",
+    note: "Operator memory endpoint.",
+  },
+  "cavi.operator.workerReady": {
+    key: "cavi.operator.workerReady",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/operator/worker/ready",
+    canonicalPath: () => "/api/plugins/cavi-control/operator/worker/ready",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/operator-control",
+    note: "Operator worker readiness endpoint.",
+  },
+  "cavi.operator.workerTasks": {
+    key: "cavi.operator.workerTasks",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/operator/worker/tasks",
+    canonicalPath: () => "/api/plugins/cavi-control/operator/worker/tasks",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/operator-control",
+    note: "Operator worker task queue endpoint.",
+  },
+  "frontDoor.dashboard": {
+    key: "frontDoor.dashboard",
+    method: "GET",
+    legacyPath: () => "/front-door/api/dashboard",
+    canonicalPath: () => "/api/plugins/front-door/dashboard",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door dashboard endpoint.",
+  },
+  "frontDoor.ideas": {
+    key: "frontDoor.ideas",
+    method: "POST",
+    legacyPath: () => "/front-door/api/ideas",
+    canonicalPath: () => "/api/plugins/front-door/ideas",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door idea creation endpoint.",
+  },
+  "frontDoor.memory": {
+    key: "frontDoor.memory",
+    method: "POST",
+    legacyPath: () => "/front-door/api/memory",
+    canonicalPath: () => "/api/plugins/front-door/memory",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door memory endpoint.",
+  },
+  "frontDoor.articles": {
+    key: "frontDoor.articles",
+    method: "POST",
+    legacyPath: () => "/front-door/api/articles",
+    canonicalPath: () => "/api/plugins/front-door/articles",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door article endpoint.",
+  },
+  "frontDoor.inbox": {
+    key: "frontDoor.inbox",
+    method: "POST",
+    legacyPath: () => "/front-door/api/inbox",
+    canonicalPath: () => "/api/plugins/front-door/inbox",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door inbox endpoint.",
+  },
+  "trading.dashboard": {
+    key: "trading.dashboard",
+    method: "GET",
+    legacyPath: () => "/trading/api/dashboard",
+    canonicalPath: () => "/api/plugins/trading/dashboard",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/trading",
+    note: "Trading workspace dashboard endpoint.",
+  },
+  "trading.researchPackets": {
+    key: "trading.researchPackets",
+    method: "GET",
+    legacyPath: () => "/trading/api/research-packets",
+    canonicalPath: () => "/api/plugins/trading/research-packets",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/trading",
+    note: "Trading research packet endpoint.",
+  },
+  "machine.dashboard": {
+    key: "machine.dashboard",
+    method: "GET",
+    legacyPath: () => "/machine/api/dashboard",
+    canonicalPath: () => "/api/plugins/machine/dashboard",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal",
+    note: "Portal media dashboard endpoint.",
+  },
+  "machine.comedyRun": {
+    key: "machine.comedyRun",
+    method: "POST",
+    legacyPath: () => "/machine/api/comedy/run",
+    canonicalPath: () => "/v1/runs",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal",
+    note: "Portal action route with gateway run fallback.",
+  },
+  "machine.ttsProviders": {
+    key: "machine.ttsProviders",
+    method: "GET",
+    legacyPath: () => "/machine/api/tts/providers",
+    canonicalPath: () => "/api/plugins/machine/tts/providers",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal",
+    note: "Portal TTS provider inventory.",
+  },
+  "machine.tts": {
+    key: "machine.tts",
+    method: "POST",
+    legacyPath: () => "/machine/api/tts",
+    canonicalPath: () => "/api/plugins/machine/tts",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal",
+    note: "Portal TTS render endpoint.",
+  },
+  "machine.media": {
+    key: "machine.media",
+    method: "GET",
+    legacyPath: (params) => `/machine/api/media?name=${p(params, "filename")}`,
+    canonicalPath: (params) =>
+      `/api/plugins/machine/media?name=${p(params, "filename")}`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal",
+    note: "Portal media fetch endpoint.",
+  },
+  "machine.memeJobs": {
+    key: "machine.memeJobs",
+    method: "GET",
+    legacyPath: () => "/machine/api/meme/jobs",
+    canonicalPath: () => "/api/plugins/machine/meme/jobs",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal",
+    note: "Portal meme job endpoint.",
+  },
+  "machine.inbox": {
+    key: "machine.inbox",
+    method: "POST",
+    legacyPath: () => "/machine/api/inbox",
+    canonicalPath: () => "/api/plugins/machine/inbox",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal",
+    note: "Portal inbox endpoint.",
+  },
+  "portalMemory.snapshot": {
+    key: "portalMemory.snapshot",
+    method: "GET",
+    legacyPath: (params) =>
+      `/cavi-control/api/portal-memory/teams/${p(params, "teamSlug")}/members/${p(params, "memberId")}/${p(params, "memoryKey")}`,
+    canonicalPath: (params) =>
+      `/api/plugins/portal-memory/teams/${p(params, "teamSlug")}/members/${p(params, "memberId")}/${p(params, "memoryKey")}`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal-memory",
+    note: "Portal memory snapshot endpoint.",
+  },
+  "martina.artifactPreview": {
+    key: "martina.artifactPreview",
+    method: "GET",
+    legacyPath: (params) =>
+      `/martina/api/artifacts/${p(params, "bucket")}/${p(params, "name")}/preview`,
+    canonicalPath: (params) =>
+      `/api/plugins/portal/martina/artifacts/${p(params, "bucket")}/${p(params, "name")}/preview`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/portal",
+    note: "Portal artifact preview endpoint.",
+  },
+  "wuTang.githubProxyWildcard": {
+    key: "wuTang.githubProxyWildcard",
+    method: "GET",
+    legacyPath: () => "/cavi-control/api/wu-tang/github/*",
+    canonicalPath: () => "/api/plugins/wu-tang/github/*",
+    classification: "compatibility-shim",
+    degradation: "hard",
+    owner: "extensions/cavi/github-proxy",
+    note: "GitHub proxy route pattern.",
+  },
+};
+
+Object.assign(CAVI_SURFACE_CONTRACTS, {
+  "frontDoor.ideaList": {
+    key: "frontDoor.ideaList",
+    method: "GET",
+    legacyPath: () => "/front-door/api/ideas",
+    canonicalPath: () => "/api/plugins/front-door/ideas",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door idea list endpoint.",
+  },
+  "frontDoor.ideaCreate": {
+    key: "frontDoor.ideaCreate",
+    method: "POST",
+    legacyPath: () => "/front-door/api/ideas",
+    canonicalPath: () => "/api/plugins/front-door/ideas",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door idea creation endpoint.",
+  },
+  "frontDoor.ideaDetail": {
+    key: "frontDoor.ideaDetail",
+    method: "GET",
+    legacyPath: (params) => `/front-door/api/ideas/${p(params, "id")}`,
+    canonicalPath: (params) => `/api/plugins/front-door/ideas/${p(params, "id")}`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door idea detail endpoint.",
+  },
+  "frontDoor.ideaPatch": {
+    key: "frontDoor.ideaPatch",
+    method: "PATCH",
+    legacyPath: (params) => `/front-door/api/ideas/${p(params, "id")}`,
+    canonicalPath: (params) => `/api/plugins/front-door/ideas/${p(params, "id")}`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door idea patch endpoint.",
+  },
+  "frontDoor.ideaPromote": {
+    key: "frontDoor.ideaPromote",
+    method: "POST",
+    legacyPath: (params) => `/front-door/api/ideas/${p(params, "id")}/promote`,
+    canonicalPath: (params) =>
+      `/api/plugins/front-door/ideas/${p(params, "id")}/promote`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door idea promotion endpoint.",
+  },
+  "frontDoor.projectList": {
+    key: "frontDoor.projectList",
+    method: "GET",
+    legacyPath: () => "/front-door/api/projects",
+    canonicalPath: () => "/api/plugins/front-door/projects",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door project list endpoint.",
+  },
+  "frontDoor.projectDetail": {
+    key: "frontDoor.projectDetail",
+    method: "GET",
+    legacyPath: (params) => `/front-door/api/projects/${p(params, "id")}`,
+    canonicalPath: (params) =>
+      `/api/plugins/front-door/projects/${p(params, "id")}`,
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door project detail endpoint.",
+  },
+  "frontDoor.articleList": {
+    key: "frontDoor.articleList",
+    method: "GET",
+    legacyPath: () => "/front-door/api/articles",
+    canonicalPath: () => "/api/plugins/front-door/articles",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door article list endpoint.",
+  },
+  "frontDoor.articleCreate": {
+    key: "frontDoor.articleCreate",
+    method: "POST",
+    legacyPath: () => "/front-door/api/articles",
+    canonicalPath: () => "/api/plugins/front-door/articles",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door article creation endpoint.",
+  },
+  "frontDoor.memoryList": {
+    key: "frontDoor.memoryList",
+    method: "GET",
+    legacyPath: () => "/front-door/api/memory",
+    canonicalPath: () => "/api/plugins/front-door/memory",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door memory list endpoint.",
+  },
+  "frontDoor.memoryCreate": {
+    key: "frontDoor.memoryCreate",
+    method: "POST",
+    legacyPath: () => "/front-door/api/memory",
+    canonicalPath: () => "/api/plugins/front-door/memory",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door memory creation endpoint.",
+  },
+  "frontDoor.inboxUpload": {
+    key: "frontDoor.inboxUpload",
+    method: "POST",
+    legacyPath: () => "/front-door/api/inbox",
+    canonicalPath: () => "/api/plugins/front-door/inbox",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/front-door",
+    note: "Front Door inbox upload endpoint.",
+  },
+  "trading.sourceRegistry": {
+    key: "trading.sourceRegistry",
+    method: "GET",
+    legacyPath: () => "/trading/api/source-registry",
+    canonicalPath: () => "/api/plugins/trading/source-registry",
+    classification: "compatibility-shim",
+    degradation: "gap",
+    owner: "extensions/cavi/trading",
+    note: "Trading source registry endpoint.",
+  },
+} satisfies Record<string, SurfaceContract>);
+
+export const SURFACE_CONTRACTS = CAVI_SURFACE_CONTRACTS;

package/src/extensions/cavi/discourse/contracts.ts

@@ -0,0 +1,9 @@
+import { API_OPERATOR } from "../contracts/paths.js";
+
+export const GATEWAY_RPC_METHODS = {
+  discourseTree: "discourse.tree",
+} as const;
+
+export function taskDiscourseExpectedContractSummary(): string {
+  return `WS ${GATEWAY_RPC_METHODS.discourseTree} (fallback: GET ${API_OPERATOR}/tasks/:taskId/discourse)`;
+}