@cavi-ai/api-client 0.1.0

package/src/extensions/cavi/operator-control/defaults.ts

@@ -0,0 +1,254 @@
+import type { OperatorControlSnapshot } from "../domain/index.js";
+
+function createEmptyTaskSummary(): OperatorControlSnapshot["tasks"]["summary"] {
+  return {
+    accepted: 0,
+    queued: 0,
+    started: 0,
+    retrying: 0,
+    blocked: 0,
+    completed: 0,
+    "dead-letter": 0,
+  };
+}
+
+export function createEmptyWorkerTransport(): OperatorControlSnapshot["status"]["worker"] {
+  return {
+    dispatchTransport: "primary-operator-2-http",
+    role: "legacy-worker-fleet",
+    configured: false,
+    baseUrl: null,
+    receiptTemplate: null,
+    authScheme: null,
+    authEnv: null,
+    authConfigured: false,
+  };
+}
+
+export function createEmptyDelegatedTransport(): OperatorControlSnapshot["status"]["delegatedFirstClassAgents"] {
+  return {
+    dispatchTransport: "delegated-http",
+    transportAliases: ["service-operator-http"],
+    role: "delegated-first-class-agent-boundary",
+    configured: false,
+    baseUrl: null,
+    authScheme: null,
+    authEnv: null,
+    authConfigured: false,
+    globalDefaultAlias: null,
+    servedTeams: [],
+    leadAliases: [],
+    defaultAliasByTeam: {},
+    teamTopology: [],
+    legacyTeams: [],
+  };
+}
+
+export function createEmptyOperatorStatus(): OperatorControlSnapshot["status"] {
+  const worker = createEmptyWorkerTransport();
+  const delegatedTransport = createEmptyDelegatedTransport();
+  return {
+    primaryOperator: "primary-operator",
+    fallbackOperator: "operator-a",
+    authorityMode: "authoritative-failover",
+    taskStorePath: "n/a",
+    registry: {
+      agentCount: 0,
+      teamCount: 0,
+      sourcePath: "n/a",
+      sourceHash: "n/a",
+      generatedAt: 0,
+    },
+    taskSummary: {
+      primaryOperator: "primary-operator",
+      fallbackOperator: "operator-a",
+      authorityMode: "authoritative-failover",
+      tasks: createEmptyTaskSummary(),
+      totals: {
+        total: 0,
+        terminal: 0,
+        active: 0,
+      },
+    },
+    runtimes: {
+      acpBackendId: null,
+      acpBackendHealthy: false,
+      sharedMemoryAuthority: "local-json-shim",
+    },
+    sharedMemory: {
+      storePath: "n/a",
+      collections: {
+        "service-context": {
+          count: 0,
+          lastVerifiedAt: null,
+          writeMode: "append-only",
+        },
+        "task-outcomes": {
+          count: 0,
+          lastVerifiedAt: null,
+          writeMode: "append-only",
+        },
+        "contract-registry": {
+          count: 0,
+          lastVerifiedAt: null,
+          writeMode: "append-only",
+        },
+        "channel-events": {
+          count: 0,
+          lastVerifiedAt: null,
+          writeMode: "append-only",
+        },
+      },
+    },
+    legacyWorkerFleet: worker,
+    delegatedFirstClassAgents: delegatedTransport,
+    worker,
+    mesh: {
+      legacyExecutionFleet: worker,
+      delegatedFirstClassAgents: delegatedTransport,
+      executionFleet: worker,
+      projectOps: {
+        mode: "task-lifecycle",
+        configured: false,
+        baseUrl: null,
+        eventEndpoint: null,
+        authScheme: null,
+        authEnv: null,
+        authConfigured: false,
+      },
+      domainOrchestrators: delegatedTransport,
+      marketing: delegatedTransport,
+      research: delegatedTransport,
+    },
+  };
+}
+
+export function createEmptyOperatorRegistry(): OperatorControlSnapshot["registryDetail"] {
+  return {
+    schema: "OperatorAgentRegistryV2",
+    generatedAt: 0,
+    sourcePath: "n/a",
+    sourceHash: "n/a",
+    agentCount: 0,
+    teamCount: 0,
+    operatorRuntime: {
+      transports: {
+        delegatedHttp: { globalDefaultAlias: null },
+      },
+    },
+    agents: [],
+    teams: [],
+    k8sCluster: [],
+    identities: [],
+    skillOwnership: [],
+  };
+}
+
+export function createEmptyOperatorTasks(): OperatorControlSnapshot["tasks"] {
+  return {
+    tasks: [],
+    summary: createEmptyTaskSummary(),
+  };
+}
+
+export function createEmptyOperatorMemory(): OperatorControlSnapshot["memory"] {
+  return {
+    authority: "local-json-shim",
+    storePath: "n/a",
+    generatedAt: 0,
+    collections: {
+      "service-context": {
+        count: 0,
+        lastVerifiedAt: null,
+        writeMode: "append-only",
+      },
+      "task-outcomes": {
+        count: 0,
+        lastVerifiedAt: null,
+        writeMode: "append-only",
+      },
+      "contract-registry": {
+        count: 0,
+        lastVerifiedAt: null,
+        writeMode: "append-only",
+      },
+      "channel-events": {
+        count: 0,
+        lastVerifiedAt: null,
+        writeMode: "append-only",
+      },
+    },
+    records: [],
+  };
+}
+
+export function createEmptyWorkerReady(): OperatorControlSnapshot["workerReady"] {
+  return {
+    status: "not-ready",
+    pending: 0,
+    active: 0,
+    shuttingDown: false,
+    auth: {
+      enabled: false,
+      scheme: "none",
+    },
+    backend: {
+      mode: "memory",
+      persistenceEnabled: false,
+      stateFile: null,
+      recoveredTasks: 0,
+    },
+  };
+}
+
+export function createEmptyWorkerTasks(): OperatorControlSnapshot["workerTasks"] {
+  return {
+    tasks: [],
+    stats: {
+      pending: 0,
+      active: 0,
+      shuttingDown: false,
+    },
+  };
+}
+
+export function createEmptyOperatorSectionStatus(): OperatorControlSnapshot["sectionStatus"] {
+  return {
+    status: {
+      available: false,
+      authoritative: true,
+      error: null,
+      sampleLimit: null,
+    },
+    registryDetail: {
+      available: false,
+      authoritative: true,
+      error: null,
+      sampleLimit: null,
+    },
+    tasks: {
+      available: false,
+      authoritative: false,
+      error: null,
+      sampleLimit: 20,
+    },
+    memory: {
+      available: false,
+      authoritative: false,
+      error: null,
+      sampleLimit: 20,
+    },
+    workerReady: {
+      available: false,
+      authoritative: true,
+      error: null,
+      sampleLimit: null,
+    },
+    workerTasks: {
+      available: false,
+      authoritative: false,
+      error: null,
+      sampleLimit: 20,
+    },
+  };
+}

package/src/extensions/cavi/operator-control/load-section.ts

@@ -0,0 +1,92 @@
+import type {
+  OperatorControlSnapshot,
+  OperatorControlSectionKey,
+} from "../domain/index.js";
+import {
+  classifyFallbackError,
+  fallbackGap,
+  type ContractGap,
+} from "../../../core/gateway/envelope/index.js";
+import { GatewayHttpError } from "../../../core/http/gateway-error.js";
+
+export type OperatorSectionLoadResult<
+  TKey extends OperatorControlSectionKey,
+  TData,
+> = {
+  key: TKey;
+  data: TData;
+  status: OperatorControlSnapshot["sectionStatus"][TKey];
+  contractGap: ContractGap | null;
+};
+
+export function createOperatorSectionStatus<
+  TKey extends OperatorControlSectionKey,
+>(params: {
+  available: boolean;
+  authoritative: boolean;
+  error: string | null;
+  sampleLimit: number | null;
+}): OperatorControlSnapshot["sectionStatus"][TKey] {
+  return {
+    available: params.available,
+    authoritative: params.authoritative,
+    error: params.error,
+    sampleLimit: params.sampleLimit,
+  };
+}
+
+export async function loadOperatorControlSection<
+  TKey extends OperatorControlSectionKey,
+  TData,
+>(params: {
+  key: TKey;
+  run: () => Promise<TData>;
+  fallback: () => TData;
+  authoritative: boolean;
+  sampleLimit: number | null;
+  expectedContract: string;
+  note: string;
+}): Promise<OperatorSectionLoadResult<TKey, TData>> {
+  try {
+    const data = await params.run();
+    return {
+      key: params.key,
+      data,
+      status: createOperatorSectionStatus({
+        available: true,
+        authoritative: params.authoritative,
+        error: null,
+        sampleLimit: params.sampleLimit,
+      }),
+      contractGap: null,
+    };
+  } catch (error) {
+    if (
+      error instanceof GatewayHttpError &&
+      (error.status === 401 || error.status === 403)
+    ) {
+      throw error;
+    }
+
+    return {
+      key: params.key,
+      data: params.fallback(),
+      status: createOperatorSectionStatus({
+        available: false,
+        authoritative: params.authoritative,
+        error: error instanceof Error ? error.message : String(error),
+        sampleLimit: params.sampleLimit,
+      }),
+      contractGap: (() => {
+        const classified = classifyFallbackError(error);
+        return fallbackGap(
+          `operator-control.${params.key}`,
+          params.expectedContract,
+          `${params.note}. ${classified.message}`,
+          classified.reason,
+          classified.httpStatus,
+        );
+      })(),
+    };
+  }
+}

package/src/extensions/cavi/portal/client.ts

@@ -0,0 +1,63 @@
+import { BaseHttpApiClient } from "../../../core/http/client.js";
+import { CAVI_CONTROL_API_ENDPOINTS, resolvePortalApiPath } from "../contracts/paths.js";
+import { resolvePath } from "../contracts/resolve.js";
+import type { HttpApiClientOptions, HttpApiTransport } from "../../../core/http/types.js";
+
+export type PortalApiClientOptions = HttpApiClientOptions & {
+  portalId: string;
+};
+
+function normalizePortalId(portalId: string): string {
+  const trimmed = portalId.trim();
+  if (!trimmed) {
+    throw new Error("PortalApiClient requires a non-empty portalId");
+  }
+  return trimmed;
+}
+
+export class PortalApiClient extends BaseHttpApiClient {
+  readonly portalId: string;
+  readonly request: HttpApiTransport;
+
+  constructor(options: PortalApiClientOptions) {
+    super("portal-api", options);
+    this.portalId = normalizePortalId(options.portalId);
+    this.request = this.createTransport();
+  }
+
+  protected portalPath(path: string): string {
+    return resolvePortalApiPath(this.portalId, path);
+  }
+
+  getDashboard<T = unknown>(): Promise<T> {
+    return this.request<T>(
+      resolvePath("portal.dashboard", "canonical", { portal: this.portalId }),
+    );
+  }
+
+  getFromPortal<T = unknown>(relativePath: string): Promise<T> {
+    return this.request<T>(this.portalPath(relativePath));
+  }
+
+  postToPortal<T = unknown>(
+    relativePath: string,
+    body: unknown,
+    idempotencyKey?: string,
+  ): Promise<T> {
+    return this.request<T>(this.portalPath(relativePath), {
+      method: "POST",
+      body,
+      idempotencyKey,
+    });
+  }
+
+  getPortalMemorySnapshot<T = unknown>(
+    teamSlug: string,
+    memberId: string,
+    memoryKey: string,
+  ): Promise<T> {
+    return this.request<T>(
+      CAVI_CONTROL_API_ENDPOINTS.portalMemorySnapshot(teamSlug, memberId, memoryKey),
+    );
+  }
+}

package/src/extensions/cavi/portal/tts.ts

@@ -0,0 +1,213 @@
+import { CAVI_CONTROL_API_ENDPOINTS } from "../contracts/paths.js";
+import type { HttpApiRequestInit } from "../../../core/http/types.js";
+import type { GatewayMediaJsonValue } from "../../../core/gateway/resources/media.js";
+
+export const PORTAL_TTS_PROVIDERS_PATH = CAVI_CONTROL_API_ENDPOINTS.portals.machine.ttsProviders;
+export const PORTAL_TTS_PATH = CAVI_CONTROL_API_ENDPOINTS.portals.machine.tts;
+
+export type PortalTtsProviderVoiceLike = {
+  id: string;
+  name?: string;
+};
+
+export type PortalTtsProviderLike = {
+  id: string;
+  label?: string;
+  name?: string;
+  configured?: boolean;
+  voices?: readonly (PortalTtsProviderVoiceLike | string)[];
+};
+
+export type PortalTtsDashboardVoiceLike = {
+  current_voice_id?: string;
+  currentVoiceId?: string;
+  current_voice_name?: string;
+  currentVoiceName?: string;
+  target_voice?: string;
+  targetVoice?: string;
+};
+
+export type PortalTtsVoiceOption = {
+  value: string;
+  label: string;
+  detail?: string;
+  source: "gateway" | "dashboard";
+  voiceId: string;
+  providerId?: string;
+  providerLabel?: string;
+  agentKey?: string;
+};
+
+export type PortalTtsAgentVoiceAssignment = {
+  agentKey: string;
+  voiceValue: string;
+  voiceId: string;
+  voiceLabel: string;
+  providerId?: string;
+  providerLabel?: string;
+  assignedAt: string;
+};
+
+export type PortalTtsJsonRequester = <T>(path: string) => Promise<T>;
+
+export type PortalTtsBlobRequester = (
+  path: string,
+  init?: Pick<HttpApiRequestInit, "body" | "headers" | "method">,
+) => Promise<Blob>;
+
+export type PortalTtsAudioTransport = {
+  requestBlob: PortalTtsBlobRequester;
+};
+
+export type PortalTtsAudioRequest = {
+  text: string;
+  voiceId?: string | null;
+  providerId?: string | null;
+  format?: string | null;
+  accept?: string | null;
+  options?: Record<string, GatewayMediaJsonValue>;
+};
+
+function cleanString(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+export function getPortalTtsProviderLabel(provider: PortalTtsProviderLike): string {
+  return cleanString(provider.label) || cleanString(provider.name) || provider.id;
+}
+
+function dashboardVoiceId(voice: PortalTtsDashboardVoiceLike): string {
+  return cleanString(voice.current_voice_id) || cleanString(voice.currentVoiceId);
+}
+
+function dashboardVoiceLabel(
+  agentKey: string,
+  voice: PortalTtsDashboardVoiceLike,
+): string {
+  return (
+    cleanString(voice.current_voice_name) ||
+    cleanString(voice.currentVoiceName) ||
+    cleanString(voice.target_voice) ||
+    cleanString(voice.targetVoice) ||
+    agentKey
+  );
+}
+
+export function buildPortalTtsVoiceOptions(params: {
+  providers?: readonly PortalTtsProviderLike[];
+  activeProviderId?: string;
+  dashboardVoices?: Record<string, PortalTtsDashboardVoiceLike>;
+}): PortalTtsVoiceOption[] {
+  const activeProviderId = cleanString(params.activeProviderId);
+  const providers = Array.isArray(params.providers)
+    ? [...params.providers].filter(
+        (provider) =>
+          provider.configured !== false &&
+          Array.isArray(provider.voices) &&
+          provider.voices.length > 0,
+      )
+    : [];
+
+  providers.sort((a, b) => {
+    const activeDiff =
+      Number(b.id === activeProviderId) - Number(a.id === activeProviderId);
+    if (activeDiff !== 0) return activeDiff;
+    return getPortalTtsProviderLabel(a).localeCompare(getPortalTtsProviderLabel(b));
+  });
+
+  const gatewayOptions = new Map<string, PortalTtsVoiceOption>();
+  for (const provider of providers) {
+    const providerId = cleanString(provider.id);
+    if (!providerId || !Array.isArray(provider.voices)) continue;
+    const providerLabel = getPortalTtsProviderLabel(provider);
+    const detail =
+      providerId === activeProviderId ? `${providerLabel} (active)` : providerLabel;
+    for (const voice of provider.voices) {
+      const voiceId = typeof voice === "string" ? cleanString(voice) : cleanString(voice.id);
+      if (!voiceId) continue;
+      const value = `gateway:${providerId}:${voiceId}`;
+      if (gatewayOptions.has(value)) continue;
+      gatewayOptions.set(value, {
+        value,
+        label: (typeof voice === "string" ? "" : cleanString(voice.name)) || voiceId,
+        detail,
+        source: "gateway",
+        voiceId,
+        providerId,
+        providerLabel,
+      });
+    }
+  }
+
+  if (gatewayOptions.size > 0) {
+    return [...gatewayOptions.values()];
+  }
+
+  return Object.entries(params.dashboardVoices ?? {})
+    .sort(([left], [right]) => left.localeCompare(right))
+    .flatMap(([agentKey, voice]) => {
+      const voiceId = dashboardVoiceId(voice);
+      if (!voiceId) return [];
+      return [
+        {
+          value: `dashboard:${agentKey}:${voiceId}`,
+          label: dashboardVoiceLabel(agentKey, voice),
+          detail: `Dashboard voice (${agentKey})`,
+          source: "dashboard" as const,
+          voiceId,
+          agentKey,
+        },
+      ];
+    });
+}
+
+export function createPortalTtsAgentVoiceAssignment(params: {
+  agentKey: string;
+  voice: PortalTtsVoiceOption;
+  assignedAt?: string;
+}): PortalTtsAgentVoiceAssignment {
+  return {
+    agentKey: params.agentKey,
+    voiceValue: params.voice.value,
+    voiceId: params.voice.voiceId,
+    voiceLabel: params.voice.label,
+    ...(params.voice.providerId ? { providerId: params.voice.providerId } : {}),
+    ...(params.voice.providerLabel ? { providerLabel: params.voice.providerLabel } : {}),
+    assignedAt: params.assignedAt ?? new Date().toISOString(),
+  };
+}
+
+export function requestPortalTtsProviders(
+  requestJson: PortalTtsJsonRequester,
+): Promise<unknown> {
+  return requestJson<unknown>(PORTAL_TTS_PROVIDERS_PATH);
+}
+
+export async function requestPortalTtsAudio(
+  transport: PortalTtsAudioTransport,
+  body: PortalTtsAudioRequest,
+): Promise<Blob> {
+  const text = cleanString(body.text);
+  if (!text) {
+    throw new Error("Enter text to synthesize.");
+  }
+  const voiceId = cleanString(body.voiceId);
+  const providerId = cleanString(body.providerId);
+  const format = cleanString(body.format);
+  const accept = cleanString(body.accept) || "audio/mpeg";
+
+  return transport.requestBlob(PORTAL_TTS_PATH, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: accept,
+    },
+    body: {
+      text,
+      ...(voiceId ? { voiceId } : {}),
+      ...(providerId ? { providerId } : {}),
+      ...(format ? { format } : {}),
+      ...(body.options ? { options: body.options } : {}),
+    },
+  });
+}

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

@@ -0,0 +1,84 @@
+import type {
+  ProjectBoardBacklogPriority,
+  ProjectBoardBacklogStatus,
+} from "../domain/index.js";
+import { resolveProjectBoardAssetPath } from "../runtime/paths.js";
+
+export const PROJECT_BOARD_CANONICAL_AVATAR_CANDIDATES = [
+  resolveProjectBoardAssetPath("project-board-wave.png"),
+  resolveProjectBoardAssetPath("project-board-reports.png"),
+  resolveProjectBoardAssetPath("project-board-laptop.png"),
+] as const;
+
+export const PROJECT_BOARD_FALLBACK_LIMITATIONS = [
+  "Cavi Control adapter used compatibility projection for Project Board payload.",
+] as const;
+
+export type ProjectBoardProfileApiResponse = {
+  name: string;
+  role: string;
+  photoPath: string | null;
+  photoUrl: string | null;
+  emails: string[];
+  lastUpdated: number;
+  storage: "json-file";
+  limitations: readonly string[];
+};
+
+export type ProjectBoardSprintApiResponse = {
+  sprint: {
+    id: string;
+    name: string;
+    goal: string;
+    startsOn: string | null;
+    endsOn: string | null;
+  };
+  statusMetrics: {
+    total: number;
+    todo: number;
+    inProgress: number;
+    blocked: number;
+    done: number;
+    completionRate: number;
+  };
+  lastUpdated: number;
+  storage: "json-file";
+  limitations: readonly string[];
+};
+
+export type ProjectBoardBacklogApiItemResponse = {
+  id: string;
+  title: string;
+  description: string | null;
+  section: string;
+  priority: ProjectBoardBacklogPriority;
+  status: ProjectBoardBacklogStatus;
+  tags: string[];
+  createdAt: number;
+  updatedAt: number;
+};
+
+export type ProjectBoardBacklogApiResponse = {
+  sections: Array<{
+    section: string;
+    items: ProjectBoardBacklogApiItemResponse[];
+  }>;
+  priorities: Record<ProjectBoardBacklogPriority, number>;
+  statusCounters: Record<ProjectBoardBacklogStatus, number>;
+  totalItems: number;
+  lastUpdated: number;
+  storage: "json-file";
+  limitations: readonly string[];
+};
+
+export type ProjectBoardCallApiAckResponse = {
+  ackId: string;
+  status: "queued";
+  action: string;
+  requestedBy: string;
+  queuedAt: number;
+  queueDepth: number;
+  note: string;
+  storage: "json-file";
+  limitations: readonly string[];
+};