@cavi-ai/api-client 0.1.0

package/src/extensions/cavi/project-board/fallback.ts

@@ -0,0 +1,129 @@
+import type { ProjectBoardWorkspaceSnapshot } from "../domain/index.js";
+import { resolveProjectBoardAssetPath } from "../runtime/paths.js";
+import { fallbackSnapshotNow as now } from "../fallbacks/snapshots/shared.js";
+
+export const fallbackProjectBoardWorkspace: ProjectBoardWorkspaceSnapshot = {
+  profile: {
+    name: "Project Board",
+    role: "Project Board Operator",
+    photoPath: resolveProjectBoardAssetPath("project-board-wave.png"),
+    photoUrl: null,
+    avatarCandidates: [
+      resolveProjectBoardAssetPath("project-board-wave.png"),
+      resolveProjectBoardAssetPath("project-board-reports.png"),
+      resolveProjectBoardAssetPath("project-board-laptop.png"),
+    ],
+    emails: ["ops@bloktix.io", "release-managers@bloktix.io"],
+    lastUpdated: now - 16 * 60_000,
+    storage: "json-file",
+    limitations: ["Mock fallback data for Cavi Control Project Board workspace."],
+  },
+  emails: [
+    { id: "ops@bloktix.io", email: "ops@bloktix.io" },
+    { id: "release-managers@bloktix.io", email: "release-managers@bloktix.io" },
+  ],
+  sprint: {
+    sprint: {
+      id: "current",
+      name: "Sprint 2026-W14",
+      goal: "Cavi Control store path realignment and Project Board data pipeline fixes",
+      startsOn: "2026-03-31",
+      endsOn: "2026-04-06",
+    },
+    statusMetrics: {
+      total: 4,
+      todo: 1,
+      inProgress: 1,
+      blocked: 1,
+      done: 1,
+      completionRate: 0.25,
+    },
+    lastUpdated: now - 14 * 60_000,
+    storage: "json-file",
+    limitations: ["Mock fallback data for Cavi Control Project Board workspace."],
+  },
+  backlog: {
+    sections: [
+      {
+        section: "now",
+        items: [
+          {
+            id: "project-board-backlog-2",
+            title: "Fix store path alignment for project-board-store.json",
+            description: "Move project-board-store.json from state/cavi-control/ to state/runtime/ to match workspace layout.",
+            section: "now",
+            priority: "p0",
+            status: "in_progress",
+            tags: ["infra", "store"],
+            createdAt: now - 120 * 60_000,
+            updatedAt: now - 20 * 60_000,
+          },
+        ],
+      },
+      {
+        section: "blocked",
+        items: [
+          {
+            id: "project-board-backlog-3",
+            title: "Validate Project Board API contract parity after store migration",
+            description: "Waiting on rebuilt Project Board container to verify response field alignment.",
+            section: "blocked",
+            priority: "p0",
+            status: "blocked",
+            tags: ["contract", "api"],
+            createdAt: now - 180 * 60_000,
+            updatedAt: now - 65 * 60_000,
+          },
+        ],
+      },
+      {
+        section: "next",
+        items: [
+          {
+            id: "project-board-backlog-1",
+            title: "Update mock fallback data to current sprint",
+            description: "Refresh mock backlog items and sprint metadata for W14.",
+            section: "next",
+            priority: "p1",
+            status: "todo",
+            tags: ["ui", "mock"],
+            createdAt: now - 200 * 60_000,
+            updatedAt: now - 45 * 60_000,
+          },
+        ],
+      },
+      {
+        section: "done",
+        items: [
+          {
+            id: "project-board-backlog-4",
+            title: "Add boot-time sync to Project Board server startup",
+            description: "GitHub field cache refreshed automatically on container start.",
+            section: "done",
+            priority: "p2",
+            status: "done",
+            tags: ["infra", "sync"],
+            createdAt: now - 210 * 60_000,
+            updatedAt: now - 90 * 60_000,
+          },
+        ],
+      },
+    ],
+    priorities: {
+      p0: 2,
+      p1: 1,
+      p2: 1,
+      p3: 0,
+    },
+    statusCounters: {
+      todo: 1,
+      in_progress: 1,
+      blocked: 1,
+      done: 1,
+    },
+    totalItems: 4,
+    lastUpdated: now - 20 * 60_000,
+    storage: "json-file",
+    limitations: ["Mock fallback data for Cavi Control Project Board workspace."],
+  },
+};

package/src/extensions/cavi/project-board/live.ts

@@ -0,0 +1,121 @@
+import type {
+  ProjectBoardBacklogDraft,
+  ProjectBoardBacklogPriority,
+  ProjectBoardBacklogStatus,
+  ProjectBoardProfile,
+  ProjectBoardWorkspaceSnapshot,
+} from "../domain/index.js";
+import { GatewayHttpError } from "../../../core/http/gateway-error.js";
+import type { JsonHttpRequest } from "../../../core/http/json-client.js";
+import { API_PROJECT_BOARD, PROJECT_BOARD_API } from "../contracts/paths.js";
+import {
+  normalizeEmailList,
+  toProjectBoardProfile,
+  toProjectBoardWorkspaceFromCompatPayload,
+  toProjectBoardWorkspaceSnapshot,
+} from "./normalize.js";
+import { asString } from "../../../core/data/guards.js";
+
+export function createProjectBoardLiveHelpers(requestJson: JsonHttpRequest) {
+  const loadProjectBoardWorkspaceLive = async (): Promise<ProjectBoardWorkspaceSnapshot> => {
+    try {
+      const [profilePayload, sprintPayload, backlogPayload] = await Promise.all(
+        [
+          requestJson<unknown>(PROJECT_BOARD_API.profile),
+          requestJson<unknown>(PROJECT_BOARD_API.sprint),
+          requestJson<unknown>(PROJECT_BOARD_API.backlog),
+        ],
+      );
+
+      return toProjectBoardWorkspaceSnapshot({
+        profilePayload,
+        sprintPayload,
+        backlogPayload,
+      });
+    } catch (error) {
+      if (!(error instanceof GatewayHttpError) || error.status !== 404) {
+        throw error;
+      }
+
+      const compatPayload = await requestJson<unknown>(API_PROJECT_BOARD);
+      return toProjectBoardWorkspaceFromCompatPayload(compatPayload);
+    }
+  };
+
+  const loadProjectBoardProfileForEmailMutation = async (): Promise<ProjectBoardProfile> => {
+    try {
+      const profilePayload = await requestJson<unknown>(PROJECT_BOARD_API.profile);
+      return toProjectBoardProfile(profilePayload);
+    } catch (error) {
+      if (!(error instanceof GatewayHttpError) || error.status !== 404) {
+        throw error;
+      }
+      const compatPayload = await requestJson<unknown>(API_PROJECT_BOARD);
+      return toProjectBoardWorkspaceFromCompatPayload(compatPayload).profile;
+    }
+  };
+
+  const persistProjectBoardEmails = async (emails: string[]): Promise<ProjectBoardProfile> => {
+    const normalizedEmails = normalizeEmailList(emails);
+
+    try {
+      const payload = await requestJson<unknown>(PROJECT_BOARD_API.profile, {
+        method: "PUT",
+        body: {
+          emails: normalizedEmails,
+        },
+      });
+      return toProjectBoardProfile(payload);
+    } catch (error) {
+      if (!(error instanceof GatewayHttpError) || error.status !== 404) {
+        throw error;
+      }
+
+      const compatPayload = await requestJson<unknown>(API_PROJECT_BOARD, {
+        method: "PUT",
+        body: {
+          emails: normalizedEmails,
+        },
+      });
+      return toProjectBoardWorkspaceFromCompatPayload(compatPayload).profile;
+    }
+  };
+
+  const toBacklogMutationPayload = (
+    draft: ProjectBoardBacklogDraft,
+  ): {
+    title: string;
+    description: string | null;
+    section: string;
+    priority: ProjectBoardBacklogPriority;
+    status: ProjectBoardBacklogStatus;
+    tags: string[];
+  } => {
+    const title = draft.title.trim();
+    const section = draft.section.trim();
+    const description = draft.description.trim();
+
+    return {
+      title,
+      description: description.length > 0 ? description : null,
+      section,
+      priority: draft.priority,
+      status: draft.status,
+      tags: Array.from(
+        new Set(
+          draft.tags
+            .map((tag) => asString(tag))
+            .filter((tag): tag is string => Boolean(tag))
+            .map((tag) => tag.toLowerCase()),
+        ),
+      ),
+    };
+  };
+
+  return {
+    loadProjectBoardWorkspaceLive,
+    loadProjectBoardProfileForEmailMutation,
+    persistProjectBoardEmails,
+    toBacklogMutationPayload,
+  };
+}

package/src/extensions/cavi/project-board/mutations.ts

@@ -0,0 +1,306 @@
+import type {
+  ProjectBoardBacklogDraft,
+  ProjectBoardCallRequest,
+  ProjectBoardEmailDraft,
+} from "../domain/index.js";
+import { GatewayHttpError } from "../../../core/http/gateway-error.js";
+import type { JsonHttpRequest } from "../../../core/http/json-client.js";
+import {
+  type MutationResult,
+  withMutationResult,
+} from "../../../core/gateway/envelope/index.js";
+import { describeHttpContract } from "../../../core/http/contracts.js";
+import {
+  PROJECT_BOARD_API,
+  projectBoardBacklogItemPath,
+} from "../contracts/paths.js";
+import {
+  PROJECT_BOARD_FALLBACK_LIMITATIONS,
+  type ProjectBoardCallApiAckResponse,
+} from "./constants.js";
+import {
+  normalizeProjectBoardBacklogItem,
+  normalizeEmailAddress,
+  parseProjectBoardCallAck,
+} from "./normalize.js";
+import { createTraceId } from "./trace-id.js";
+import type { createProjectBoardLiveHelpers } from "./live.js";
+
+type ProjectBoardLiveHelpers = ReturnType<typeof createProjectBoardLiveHelpers>;
+
+export function createProjectBoardMutations(
+  requestJson: JsonHttpRequest,
+  projectBoardLive: ProjectBoardLiveHelpers,
+) {
+  const {
+    loadProjectBoardProfileForEmailMutation,
+    persistProjectBoardEmails,
+    toBacklogMutationPayload,
+  } = projectBoardLive;
+
+  return {
+    createProjectBoardEmail: async (
+      draft: ProjectBoardEmailDraft,
+    ): Promise<MutationResult<{ id: string; email: string }>> =>
+      withMutationResult({
+        area: "project-board-email-create",
+        expectedContract: describeHttpContract(
+          "PUT",
+          PROJECT_BOARD_API.profile,
+          "{ emails: string[] }",
+        ),
+        note: "Project Board profile email mutation failed",
+        fallback: () => ({
+          id: normalizeEmailAddress(draft.email) ?? `mock-email-${Date.now()}`,
+          email:
+            normalizeEmailAddress(draft.email) ??
+            draft.email.trim().toLowerCase(),
+        }),
+        run: async () => {
+          const email = normalizeEmailAddress(draft.email);
+          if (!email) {
+            throw new Error("Valid email address required.");
+          }
+
+          const profile = await loadProjectBoardProfileForEmailMutation();
+          if (profile.emails.includes(email)) {
+            return { id: email, email };
+          }
+
+          const updatedProfile = await persistProjectBoardEmails([
+            ...profile.emails,
+            email,
+          ]);
+          const persistedEmail =
+            updatedProfile.emails.find((entry) => entry === email) ?? email;
+          return {
+            id: persistedEmail,
+            email: persistedEmail,
+          };
+        },
+      }),
+
+    updateProjectBoardEmail: async (
+      emailId: string,
+      draft: ProjectBoardEmailDraft,
+    ): Promise<MutationResult<{ id: string; email: string }>> =>
+      withMutationResult({
+        area: "project-board-email-update",
+        expectedContract: describeHttpContract(
+          "PUT",
+          PROJECT_BOARD_API.profile,
+          "{ emails: string[] }",
+        ),
+        note: "Project Board profile email update failed",
+        fallback: () => ({
+          id: normalizeEmailAddress(draft.email) ?? emailId,
+          email:
+            normalizeEmailAddress(draft.email) ??
+            draft.email.trim().toLowerCase(),
+        }),
+        run: async () => {
+          const nextEmail = normalizeEmailAddress(draft.email);
+          if (!nextEmail) {
+            throw new Error("Valid email address required.");
+          }
+
+          const profile = await loadProjectBoardProfileForEmailMutation();
+          const currentId = normalizeEmailAddress(emailId);
+          if (!currentId || !profile.emails.includes(currentId)) {
+            throw new Error("Email recipient not found.");
+          }
+
+          const nextEmails = profile.emails.map((email) =>
+            email === currentId ? nextEmail : email,
+          );
+          const updatedProfile = await persistProjectBoardEmails(nextEmails);
+          const persistedEmail =
+            updatedProfile.emails.find((email) => email === nextEmail) ??
+            nextEmail;
+
+          return {
+            id: persistedEmail,
+            email: persistedEmail,
+          };
+        },
+      }),
+
+    removeProjectBoardEmail: async (
+      emailId: string,
+    ): Promise<MutationResult<{ id: string }>> =>
+      withMutationResult({
+        area: "project-board-email-delete",
+        expectedContract: describeHttpContract(
+          "PUT",
+          PROJECT_BOARD_API.profile,
+          "{ emails: string[] }",
+        ),
+        note: "Project Board profile email delete failed",
+        fallback: () => ({ id: emailId }),
+        run: async () => {
+          const normalizedEmailId = normalizeEmailAddress(emailId);
+          if (!normalizedEmailId) {
+            throw new Error("Email recipient id is invalid.");
+          }
+
+          const profile = await loadProjectBoardProfileForEmailMutation();
+          const nextEmails = profile.emails.filter(
+            (email) => email !== normalizedEmailId,
+          );
+
+          if (nextEmails.length === profile.emails.length) {
+            throw new Error("Email recipient not found.");
+          }
+
+          await persistProjectBoardEmails(nextEmails);
+          return { id: normalizedEmailId };
+        },
+      }),
+
+    createProjectBoardBacklogItem: async (draft: ProjectBoardBacklogDraft) =>
+      withMutationResult({
+        area: "project-board-backlog-create",
+        expectedContract: describeHttpContract("POST", PROJECT_BOARD_API.backlog),
+        note: "Project Board backlog create failed",
+        fallback: () => ({
+          id: `mock-backlog-${Date.now()}`,
+          title: draft.title.trim(),
+          description: draft.description.trim() || null,
+          section: draft.section.trim().toLowerCase() || "inbox",
+          priority: draft.priority,
+          status: draft.status,
+          tags: draft.tags,
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        }),
+        run: async () => {
+          const payload = toBacklogMutationPayload(draft);
+          const response = await requestJson<unknown>(PROJECT_BOARD_API.backlog, {
+            method: "POST",
+            body: payload,
+          });
+          const item = normalizeProjectBoardBacklogItem(response);
+          if (!item) {
+            throw new Error("Gateway returned invalid backlog item payload.");
+          }
+          return item;
+        },
+      }),
+
+    updateProjectBoardBacklogItem: async (itemId: string, draft: ProjectBoardBacklogDraft) =>
+      withMutationResult({
+        area: "project-board-backlog-update",
+        expectedContract: describeHttpContract(
+          "PATCH",
+          `${PROJECT_BOARD_API.backlog}/:id`,
+        ),
+        note: "Project Board backlog update failed",
+        fallback: () => ({
+          id: itemId,
+          title: draft.title.trim(),
+          description: draft.description.trim() || null,
+          section: draft.section.trim().toLowerCase() || "inbox",
+          priority: draft.priority,
+          status: draft.status,
+          tags: draft.tags,
+          createdAt: Date.now(),
+          updatedAt: Date.now(),
+        }),
+        run: async () => {
+          const payload = toBacklogMutationPayload(draft);
+          const response = await requestJson<unknown>(
+            projectBoardBacklogItemPath(itemId),
+            {
+              method: "PATCH",
+              body: payload,
+            },
+          );
+          const item = normalizeProjectBoardBacklogItem(response);
+          if (!item) {
+            throw new Error("Gateway returned invalid backlog item payload.");
+          }
+          return item;
+        },
+      }),
+
+    callProjectBoard: async (request: ProjectBoardCallRequest) =>
+      withMutationResult({
+        area: "project-board-call",
+        expectedContract: describeHttpContract(
+          "POST",
+          PROJECT_BOARD_API.call,
+          "{ action, requestedBy, metadata }",
+        ),
+        note: "Project Board call endpoint failed",
+        fallback: () => {
+          const traceId = createTraceId();
+          return {
+            ackId: `project-board-call-${traceId}`,
+            status: "queued" as const,
+            action: request.action,
+            requestedBy: request.requestedBy,
+            queuedAt: Date.now(),
+            queueDepth: 0,
+            note: "Project Board call endpoint unavailable. Action stored as local fallback only.",
+            storage: "json-file" as const,
+            limitations: PROJECT_BOARD_FALLBACK_LIMITATIONS,
+            traceId,
+          };
+        },
+        run: async () => {
+          const traceId = createTraceId();
+          const action = request.action.trim();
+          const requestedBy = request.requestedBy.trim() || "cavi-control-ui";
+
+          if (!action) {
+            throw new Error("Project Board action is required.");
+          }
+
+          const payload = {
+            action,
+            requestedBy,
+            metadata: {
+              ...request.metadata,
+              source: "cavi-control-ui",
+              traceId,
+            },
+          };
+
+          try {
+            const response = await requestJson<ProjectBoardCallApiAckResponse>(
+              PROJECT_BOARD_API.call,
+              {
+                method: "POST",
+                body: payload,
+              },
+            );
+            return parseProjectBoardCallAck(response, {
+              action,
+              requestedBy,
+              traceId,
+            });
+          } catch (error) {
+            if (
+              !(error instanceof GatewayHttpError) ||
+              (error.status !== 422 && error.status !== 404)
+            ) {
+              throw error;
+            }
+
+            const compatResponse = await requestJson<unknown>(PROJECT_BOARD_API.call, {
+              method: "POST",
+              body: {
+                instruction: action,
+              },
+            });
+
+            return parseProjectBoardCallAck(compatResponse, {
+              action,
+              requestedBy,
+              traceId,
+            });
+          }
+        },
+      }),
+  };
+}