govoplan-docs/webui/src/api/docs.ts

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

export type DocsModule = {
  id: string;
  name: string;
  version: string;
  dependencies: string[];
  optional_dependencies: string[];
  permission_count: number;
  role_template_count: number;
  nav_count: number;
  route_count: number;
  frontend_package?: string | null;
  backend_route_contributed: boolean;
  migration_module_id?: string | null;
  capabilities: string[];
  documentation_count: number;
  documentation_provider_count: number;
};

export type DocsRoute = {
  module_id: string;
  path: string;
  label: string;
  icon?: string | null;
  section?: string | null;
  source: string;
  component?: string | null;
  required_all: string[];
  required_any: string[];
  order: number;
  visible: boolean;
  reason: string;
};

export type DocsPermission = {
  scope: string;
  label: string;
  description: string;
  category: string;
  level: "system" | "tenant";
  module_id: string;
  resource: string;
  action: string;
  deprecated: boolean;
  granted: boolean;
};

export type DocsOptionalModuleEvidence = {
  module_id: string;
  source_module_id: string;
  status: "installed" | "not_installed" | string;
  reason: string;
};

export type DocsSource = {
  label: string;
  source: string;
  layer: string;
};

export type DocsDocumentationCondition = {
  required_modules: string[];
  any_modules: string[];
  missing_modules: string[];
  required_capabilities: string[];
  required_scopes: string[];
  any_scopes: string[];
  configuration_keys: string[];
};

export type DocsDocumentationLink = {
  label: string;
  href: string;
  kind: string;
};

export type DocsTopicKind = "workflow" | "reference" | "pattern" | "system" | string;

export type DocsDocumentationTopic = {
  id: string;
  source_module_id: string;
  kind: DocsTopicKind;
  anchor_id: string;
  title: string;
  summary: string;
  body: string;
  layer: "always" | "configured" | "available" | "evidence" | string;
  target_layer: string;
  documentation_types: Array<"admin" | "user" | string>;
  active: boolean;
  reason: string;
  blockers: {
    modules: string[];
    capabilities: string[];
    scopes: string[];
  };
  audience: string[];
  order: number;
  i18n_key: string;
  locale: string;
  translation_locale: string;
  conditions: DocsDocumentationCondition[];
  links: DocsDocumentationLink[];
  related_modules: string[];
  unlocks: string[];
  configuration_keys: string[];
  metadata: Record<string, unknown>;
};

export type DocsContext = {
  actor: {
    tenant_id?: string;
    user_id?: string;
    scope_count?: number;
    documentation_type: "admin" | "user";
    locale: string;
    available_documentation_types: Array<"admin" | "user">;
  };
  summary: {
    module_count: number;
    visible_route_count: number;
    available_route_count: number;
    permission_count: number;
    granted_permission_count: number;
    optional_module_count: number;
    documentation_topic_count: number;
    configured_documentation_topic_count: number;
    workflow_topic_count: number;
    reference_topic_count: number;
    pattern_topic_count: number;
    system_topic_count: number;
  };
  topic_groups: {
    workflow: DocsDocumentationTopic[];
    reference: DocsDocumentationTopic[];
    pattern: DocsDocumentationTopic[];
    system: DocsDocumentationTopic[];
    [kind: string]: DocsDocumentationTopic[];
  };
  layers: {
    always: {
      documentation: DocsDocumentationTopic[];
    };
    configured: {
      modules: DocsModule[];
      routes: DocsRoute[];
      permissions: DocsPermission[];
      documentation: DocsDocumentationTopic[];
    };
    available: {
      routes: DocsRoute[];
      permissions: DocsPermission[];
      documentation: DocsDocumentationTopic[];
    };
    evidence: {
      optional_modules: DocsOptionalModuleEvidence[];
      sources: DocsSource[];
      documentation: DocsDocumentationTopic[];
    };
  };
};

export function fetchDocsContext(settings: ApiSettings, options: { documentationType?: "admin" | "user"; locale?: string } = {}): Promise<DocsContext> {
  const params = new URLSearchParams();
  if (options.documentationType) params.set("type", options.documentationType);
  if (options.locale) params.set("locale", options.locale);
  const query = params.toString();
  return apiFetch(settings, `/api/v1/docs/context${query ? `?${query}` : ""}`);
}