govoplan-connectors/webui/src/api/externalKnowledge.ts

import { apiFetch, apiPath, type ApiSettings } from "@govoplan/core-webui";

export type KnowledgeDiagnostic = {
  severity: "info" | "warning" | "error";
  code: string;
  message: string;
  object_ref?: string | null;
  field?: string | null;
  retryable: boolean;
  details: Record<string, unknown>;
};

export type KnowledgeNamespaceMapping = {
  source_namespace_id: number;
  source_name: string;
  target_space_ref: string;
  target_path_prefix: string;
  include: boolean;
  visibility?: "tenant" | "restricted" | null;
  acl_tokens: string[];
};

export type KnowledgeProfile = {
  id: string;
  tenant_id: string;
  configuration_id: string;
  status: "active" | "paused";
  product: string;
  product_version?: string | null;
  desired_maturity: "discover" | "link" | "search" | "read" | "publish" | "synchronize" | "migrate";
  discovered_maturity: string;
  source_authority_mode: "external_authoritative" | "external_mirror" | "governed_sync" | "linked_reference";
  default_visibility: "tenant" | "restricted";
  default_acl_tokens: string[];
  namespace_mappings: KnowledgeNamespaceMapping[];
  capabilities: string[];
  discovery_revision?: string | null;
  health_status: string;
  health_details: Record<string, unknown>;
  discovered_at?: string | null;
  last_sync_cursor?: string | null;
  last_high_watermark?: string | null;
  resource_revision: number;
  credential_reference_present: boolean;
  endpoint_configured: boolean;
  created_at: string;
  updated_at: string;
};

export type KnowledgeObject = {
  id: string;
  profile_id: string;
  object_type: string;
  external_id: string;
  external_page_id?: string | null;
  external_revision_id?: string | null;
  namespace_id?: number | null;
  title: string;
  canonical_url?: string | null;
  status: string;
  source_revision: string;
  visibility: string;
  acl_tokens: string[];
  mapped_data: Record<string, unknown>;
  observed_at: string;
  resource_revision: number;
};

export type KnowledgeRun = {
  id: string;
  profile_id: string;
  mode: string;
  idempotency_key: string;
  status: string;
  cursor_before?: string | null;
  cursor_after?: string | null;
  high_watermark?: string | null;
  counts: Record<string, number>;
  effects: Array<Record<string, unknown>>;
  diagnostics: KnowledgeDiagnostic[];
  provenance: Record<string, unknown>;
  started_at: string;
  finished_at?: string | null;
  created_at: string;
};

export type KnowledgeDiscovery = {
  profile: KnowledgeProfile;
  product: string;
  product_version?: string | null;
  capabilities: string[];
  namespaces: Array<Record<string, unknown>>;
  extensions: Array<Record<string, unknown>>;
  maturity: string;
  health_status: string;
  diagnostics: KnowledgeDiagnostic[];
  revision: string;
};

export type KnowledgeMigrationPreview = {
  run: KnowledgeRun;
  target_space_ref: string;
  source_revision: string;
  source_fingerprint: string;
  summary: Record<string, number>;
  effects: Array<Record<string, unknown>>;
  diagnostics: KnowledgeDiagnostic[];
  truncated: boolean;
  can_apply: boolean;
};

export type KnowledgePublishResult = {
  run: KnowledgeRun;
  external_reference: Record<string, unknown>;
  accepted: boolean;
  outcome_unknown: boolean;
};

const ROOT = "/api/v1/connectors/knowledge";

export async function listKnowledgeProfiles(settings: ApiSettings): Promise<KnowledgeProfile[]> {
  const response = await apiFetch<{ items: KnowledgeProfile[] }>(settings, `${ROOT}/profiles`);
  return response.items;
}

export function createKnowledgeProfile(
  settings: ApiSettings,
  payload: Record<string, unknown>
): Promise<KnowledgeProfile> {
  return apiFetch(settings, `${ROOT}/profiles`, {
    method: "POST",
    body: JSON.stringify(payload)
  });
}

export function updateKnowledgeProfile(
  settings: ApiSettings,
  profileId: string,
  payload: Record<string, unknown>
): Promise<KnowledgeProfile> {
  return apiFetch(settings, `${ROOT}/profiles/${encodeURIComponent(profileId)}`, {
    method: "PUT",
    body: JSON.stringify(payload)
  });
}

export function discoverKnowledgeProfile(
  settings: ApiSettings,
  profileId: string
): Promise<KnowledgeDiscovery> {
  return apiFetch(settings, `${ROOT}/profiles/${encodeURIComponent(profileId)}/discover`, {
    method: "POST"
  });
}

export function synchronizeKnowledgeProfile(
  settings: ApiSettings,
  profileId: string,
  payload: Record<string, unknown>
): Promise<KnowledgeRun> {
  return apiFetch(settings, `${ROOT}/profiles/${encodeURIComponent(profileId)}/sync`, {
    method: "POST",
    body: JSON.stringify(payload)
  });
}

export async function listKnowledgeObjects(
  settings: ApiSettings,
  profileId: string
): Promise<KnowledgeObject[]> {
  const response = await apiFetch<{ items: KnowledgeObject[] }>(
    settings,
    apiPath(`${ROOT}/profiles/${encodeURIComponent(profileId)}/objects`, { limit: 100 })
  );
  return response.items;
}

export async function listKnowledgeRuns(
  settings: ApiSettings,
  profileId?: string
): Promise<KnowledgeRun[]> {
  const response = await apiFetch<{ items: KnowledgeRun[] }>(
    settings,
    apiPath(`${ROOT}/runs`, { profile_id: profileId || undefined, limit: 100 })
  );
  return response.items;
}

export function previewKnowledgeMigration(
  settings: ApiSettings,
  profileId: string,
  payload: Record<string, unknown>
): Promise<KnowledgeMigrationPreview> {
  return apiFetch(
    settings,
    `${ROOT}/profiles/${encodeURIComponent(profileId)}/migration-dry-runs`,
    { method: "POST", body: JSON.stringify(payload) }
  );
}

export function publishKnowledgePage(
  settings: ApiSettings,
  profileId: string,
  externalPageId: string,
  payload: Record<string, unknown>
): Promise<KnowledgePublishResult> {
  return apiFetch(
    settings,
    `${ROOT}/profiles/${encodeURIComponent(profileId)}/pages/${encodeURIComponent(externalPageId)}/publish`,
    { method: "POST", body: JSON.stringify(payload) }
  );
}