api

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 18, 2026 License: AGPL-3.0, AGPL-3.0-or-later Imports: 28 Imported by: 0

Documentation

Overview

Package api provides shared schema mapping from Kora field types to JSON Schema. Used by OpenAPI, MCP, and Chat to generate consistent tool/schema definitions.

Index

Constants

This section is empty.

Variables

View Source 
var APIDefaultLimit = 50

APIDefaultLimit and APIMaxLimit control pagination (set from common config at startup).

View Source 
var APIMaxLimit = 500
View Source 
var AppBranding = Branding{AppName: "Kora", PrimaryColor: "#2563eb"}

AppBranding is the global branding config (set from common config at startup).

Functions

func DocTypeToJSONSchema 

func DocTypeToJSONSchema(dt *doctype.DocType, registry *doctype.Registry) map[string]any

DocTypeToJSONSchema converts a DocType into a JSON Schema object.

func FieldToJSONSchema 

func FieldToJSONSchema(f *doctype.Field) map[string]any

FieldToJSONSchema maps a Kora field definition to a JSON Schema property.

func GenerateOpenAPISpec 

func GenerateOpenAPISpec(reg *doctype.Registry, siteName string) *openapi3.T

GenerateOpenAPISpec builds the full OpenAPI 3.x document from a registry.

func RegisterRoutes 

func RegisterRoutes(router *gin.Engine, registry *doctype.Registry, txManager *orm.TxManager)

RegisterRoutes registers all CRUD routes for all DocTypes in the registry on a full Engine.

func RegisterRoutesOnGroup 

func RegisterRoutesOnGroup(apiGroup *gin.RouterGroup, registry *doctype.Registry, txManager *orm.TxManager)

RegisterRoutesOnGroup registers all CRUD routes on an existing RouterGroup. This allows the caller to apply middleware (e.g., auth) before the group.

func RegisterSystemRoutes 

func RegisterSystemRoutes(apiGroup *gin.RouterGroup, handler *Handler)

RegisterSystemRoutes registers system endpoints on the given API group.

func SetAPILimits 

func SetAPILimits(def, max int)

SetAPILimits sets pagination limits from config.

Types

type AIConfig 

type AIConfig struct {
	MaxRounds           int     // Max tool-calling rounds (safety cap)
	TokenBudget         int     // Context window budget in tokens
	CompactionThreshold float64 // 0.0-1.0, when to start compacting history
	MaxToolResultChars  int     // Cap on a single tool result string
	StallThreshold      int     // Consecutive identical tool calls before nudge
	MaxToolErrors       int     // Total tool errors before circuit breaker
	MaxTokensPerCall    int     // max_tokens per AI API call
	HTTPTimeoutSec      int     // Timeout in seconds for AI provider HTTP calls
	MaxRetries          int     // Retries on transient AI errors (429, 503)
	RetryBackoffMs      int     // Base backoff in milliseconds
	HistoryLimit        int     // Max incoming history messages from client
}

AIConfig holds all configurable thresholds for the AI chat pipeline. Every value has a sensible default; site-level overrides are loaded from the secret store with an "ai." key prefix.

func DefaultAIConfig 

func DefaultAIConfig() AIConfig

DefaultAIConfig returns sane defaults that work for most models.

func LoadAIConfig 

func LoadAIConfig(store *secret.Store, siteName, model string) AIConfig

LoadAIConfig returns the effective AIConfig for the given model and site. Resolution order: DefaultAIConfig → model-specific defaults → site-level overrides from the secret store (keys prefixed with "ai.").

type Branding 

type Branding struct {
	AppName      string `json:"app_name"`
	PrimaryColor string `json:"primary_color"`
}

Branding holds per-site branding configuration.

type ChatMessage 

type ChatMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

ChatMessage is a single turn in the conversation.

type ChatRequest 

type ChatRequest struct {
	Message string        `json:"message"`
	History []ChatMessage `json:"history,omitempty"`
	Model   string        `json:"model,omitempty"` // override default model
}

ChatRequest is the JSON body for POST /api/chat.

type ChatResponse 

type ChatResponse struct {
	Reply  string `json:"reply"`
	Action string `json:"action,omitempty"` // what the AI did (e.g., "listed 3 customers")
}

ChatResponse is the JSON response from POST /api/chat.

type ConsoleHandler 

type ConsoleHandler struct {
	SystemGuard        *auth.SystemGuard
	SiteRouter         *net.SiteRouter
	PlatformDBType     string
	PlatformDBHost     string
	PlatformDBPort     int
	PlatformDBUser     string
	PlatformDBPassword string
	PlatformDB         *sql.DB // Existing platform DB connection (for LibSQL reuse)
}

ConsoleHandler holds dependencies for console API endpoints.

func NewConsoleHandler 

func NewConsoleHandler(guard *auth.SystemGuard, sr *net.SiteRouter, dbType, dbHost, dbUser, dbPassword string, dbPort int, platformDB *sql.DB) *ConsoleHandler

NewConsoleHandler creates a console API handler.

func (*ConsoleHandler) HandleChangePassword 

func (h *ConsoleHandler) HandleChangePassword(c *gin.Context)

HandleChangePassword forces a password change (required on first login with default creds). POST /api/console/change-password

func (*ConsoleHandler) HandleCreateSite 

func (h *ConsoleHandler) HandleCreateSite(c *gin.Context)

HandleCreateSite creates a new site: database, config, bootstrap, admin user. POST /api/console/sites Only hostname, admin_email, and admin_password are required. DB fields are optional — platform defaults from env vars are used when empty.

func (*ConsoleHandler) HandleDeleteSite 

func (h *ConsoleHandler) HandleDeleteSite(c *gin.Context)

HandleDeleteSite deletes a site and all its data. DELETE /api/console/sites/:name Requires confirmation: {"confirm": "<hostname>"}

func (*ConsoleHandler) HandleListSites 

func (h *ConsoleHandler) HandleListSites(c *gin.Context)

HandleListSites returns all loaded sites with status. Falls back to querying the database directly when no sites are loaded (e.g. after container redeploy where site_config.yaml files were lost but DB data persists). GET /api/console/sites

func (*ConsoleHandler) HandleLogin 

func (h *ConsoleHandler) HandleLogin(c *gin.Context)

HandleLogin authenticates a console super-admin. POST /api/console/login

func (*ConsoleHandler) HandleResetSitePassword 

func (h *ConsoleHandler) HandleResetSitePassword(c *gin.Context)

HandleResetSitePassword resets a site user's password. POST /api/console/sites/:name/reset-password

func (*ConsoleHandler) HandleUpdateSite 

func (h *ConsoleHandler) HandleUpdateSite(c *gin.Context)

HandleUpdateSite updates site metadata (domains). PUT /api/console/sites/:name

func (*ConsoleHandler) RequireConsoleAuth 

func (h *ConsoleHandler) RequireConsoleAuth(c *gin.Context)

RequireConsoleAuth is middleware that validates the console session. Accepts Authorization: Bearer <token> header OR kora_console_sid cookie.

type DocTypeNavItem 

type DocTypeNavItem struct {
	Name    string `json:"name"`
	Label   string `json:"label"`
	Icon    string `json:"icon,omitempty"`
	IsChild bool   `json:"is_child"`
}

DocTypeNavItem is a single DocType entry in the navigation.

type ErrorResponse 

type ErrorResponse struct {
	Error any   `json:"error"`
	Meta  *Meta `json:"meta,omitempty"`
}

ErrorResponse is the standard error response envelope.

type Handler 

type Handler struct {
	Registry  *doctype.Registry
	TxManager *orm.TxManager
}

Handler holds dependencies for API handlers. Registry and TxManager are fallbacks; handlers read site context from the request.

func NewHandler 

func NewHandler(registry *doctype.Registry, txManager *orm.TxManager) *Handler

NewHandler creates a new API handler.

func (*Handler) HandleAuthProviders 

func (h *Handler) HandleAuthProviders(c *gin.Context)

HandleAuthProviders returns enabled authentication providers. Public endpoint — no auth required.

func (*Handler) HandleChat 

func (h *Handler) HandleChat(c *gin.Context)

HandleChat processes a chat message, calls the AI provider with function definitions, executes any tool calls via the ORM, and returns the AI's response. POST /api/chat

func (*Handler) HandleConfigDiff 

func (h *Handler) HandleConfigDiff(c *gin.Context)

HandleConfigDiff returns the diff between two config versions.

func (*Handler) HandleConfigImport 

func (h *Handler) HandleConfigImport(c *gin.Context)

HandleConfigImport imports a YAML config file and returns parsed DocType JSON. POST /api/system/config/import

func (*Handler) HandleConfigVersion 

func (h *Handler) HandleConfigVersion(c *gin.Context)

HandleConfigVersion gets a single config version snapshot.

func (*Handler) HandleConfigVersionActivate 

func (h *Handler) HandleConfigVersionActivate(c *gin.Context)

HandleConfigVersionActivate activates a Draft version. POST /api/system/config/versions/:id/activate

func (*Handler) HandleConfigVersionDiscard 

func (h *Handler) HandleConfigVersionDiscard(c *gin.Context)

HandleConfigVersionDiscard discards a Draft version. POST /api/system/config/versions/:id/discard

func (*Handler) HandleConfigVersionRollback 

func (h *Handler) HandleConfigVersionRollback(c *gin.Context)

HandleConfigVersionRollback activates a Superseded version (rollback). POST /api/system/config/versions/:id/rollback

func (*Handler) HandleConfigVersions 

func (h *Handler) HandleConfigVersions(c *gin.Context)

HandleConfigVersions lists all config versions.

func (*Handler) HandleCreate 

func (h *Handler) HandleCreate(c *gin.Context)

HandleCreate handles POST /api/resource/{doctype}

func (*Handler) HandleDelete 

func (h *Handler) HandleDelete(c *gin.Context)

HandleDelete handles DELETE /api/resource/{doctype}/{name}

func (*Handler) HandleGet 

func (h *Handler) HandleGet(c *gin.Context)

HandleGet handles GET /api/resource/{doctype}/{name}

func (*Handler) HandleList 

func (h *Handler) HandleList(c *gin.Context)

HandleList handles GET /api/resource/{doctype}

func (*Handler) HandleOpenAPI 

func (h *Handler) HandleOpenAPI(c *gin.Context)

HandleOpenAPI returns the OpenAPI 3.x spec for the current site.

func (*Handler) HandleSecretDelete 

func (h *Handler) HandleSecretDelete(c *gin.Context)

HandleSecretDelete deletes a secret by key name. DELETE /api/system/secrets/:key

func (*Handler) HandleSecretList 

func (h *Handler) HandleSecretList(c *gin.Context)

HandleSecretList returns all secret key names and timestamps for the current site. Values are NEVER returned. GET /api/system/secrets

func (*Handler) HandleSecretSet 

func (h *Handler) HandleSecretSet(c *gin.Context)

HandleSecretSet creates or updates a secret. POST /api/system/secrets

func (*Handler) HandleSwaggerUI 

func (h *Handler) HandleSwaggerUI(c *gin.Context)

HandleSwaggerUI serves the Swagger UI HTML page.

func (*Handler) HandleSystemDoctype 

func (h *Handler) HandleSystemDoctype(c *gin.Context)

HandleSystemDoctype returns the full DocType schema with workflow and permissions. GET /api/system/doctype/:doctype Optional query param: ?format=yaml to get raw YAML output. Optional query param: ?state=current_state to get available transitions.

func (*Handler) HandleSystemDoctypeCreate 

func (h *Handler) HandleSystemDoctypeCreate(c *gin.Context)

HandleSystemDoctypeCreate creates a new DocType from JSON body. POST /api/system/doctype?activate=true|false

func (*Handler) HandleSystemDoctypeDelete 

func (h *Handler) HandleSystemDoctypeDelete(c *gin.Context)

HandleSystemDoctypeDelete removes a DocType configuration. DELETE /api/system/doctype/:doctype

func (*Handler) HandleSystemDoctypeDryRun 

func (h *Handler) HandleSystemDoctypeDryRun(c *gin.Context)

HandleSystemDoctypeDryRun returns the impact analysis for a proposed doctype change. POST /api/system/doctype/dry-run

func (*Handler) HandleSystemDoctypeReferences 

func (h *Handler) HandleSystemDoctypeReferences(c *gin.Context)

HandleSystemDoctypeReferences returns other doctypes that link to the given doctype. GET /api/system/doctype/:doctype/references

func (*Handler) HandleSystemDoctypeUpdate 

func (h *Handler) HandleSystemDoctypeUpdate(c *gin.Context)

HandleSystemDoctypeUpdate updates an existing DocType. PUT /api/system/doctype/:doctype?activate=true|false

func (*Handler) HandleSystemDoctypeValidate 

func (h *Handler) HandleSystemDoctypeValidate(c *gin.Context)

HandleSystemDoctypeValidate validates a DocType JSON or YAML body without saving. POST /api/system/doctype/validate Accepts JSON (Content-Type: application/json) or YAML (Content-Type: application/x-yaml). Returns structured errors with line numbers for unknown keys and validation issues.

func (*Handler) HandleSystemDoctypes 

func (h *Handler) HandleSystemDoctypes(c *gin.Context)

HandleSystemDoctypes returns a flat list of all DocTypes. GET /api/system/doctypes

func (*Handler) HandleSystemNavigation 

func (h *Handler) HandleSystemNavigation(c *gin.Context)

HandleSystemNavigation returns the navigation config (sidebar, branding, user). GET /api/system/navigation

func (*Handler) HandleSystemPermissions 

func (h *Handler) HandleSystemPermissions(c *gin.Context)

HandleSystemPermissions returns all permissions. GET /api/system/permissions

func (*Handler) HandleSystemPermissionsSave 

func (h *Handler) HandleSystemPermissionsSave(c *gin.Context)

HandleSystemPermissionsSave replaces all permissions. PUT /api/system/permissions

func (*Handler) HandleSystemRoleCreate 

func (h *Handler) HandleSystemRoleCreate(c *gin.Context)

HandleSystemRoleCreate creates a new role. POST /api/system/roles

func (*Handler) HandleSystemRoleDelete 

func (h *Handler) HandleSystemRoleDelete(c *gin.Context)

HandleSystemRoleDelete deletes a role. DELETE /api/system/roles/:name

func (*Handler) HandleSystemRoleUpdate 

func (h *Handler) HandleSystemRoleUpdate(c *gin.Context)

HandleSystemRoleUpdate updates an existing role. PUT /api/system/roles/:name

func (*Handler) HandleSystemRoles 

func (h *Handler) HandleSystemRoles(c *gin.Context)

HandleSystemRoles returns all roles. GET /api/system/roles

func (*Handler) HandleSystemWorkflowByDoctype 

func (h *Handler) HandleSystemWorkflowByDoctype(c *gin.Context)

HandleSystemWorkflowByDoctype returns the workflow for a specific doctype. GET /api/system/workflows/:doctype

func (*Handler) HandleSystemWorkflowDelete 

func (h *Handler) HandleSystemWorkflowDelete(c *gin.Context)

HandleSystemWorkflowDelete removes a workflow for a doctype. DELETE /api/system/workflows/:doctype

func (*Handler) HandleSystemWorkflowSave 

func (h *Handler) HandleSystemWorkflowSave(c *gin.Context)

HandleSystemWorkflowSave creates or updates a workflow. POST /api/system/workflows

func (*Handler) HandleSystemWorkflows 

func (h *Handler) HandleSystemWorkflows(c *gin.Context)

HandleSystemWorkflows returns all workflows. GET /api/system/workflows

func (*Handler) HandleUpdate 

func (h *Handler) HandleUpdate(c *gin.Context)

HandleUpdate handles PUT /api/resource/{doctype}/{name}

func (*Handler) HandleUpload 

func (h *Handler) HandleUpload(c *gin.Context)

HandleUpload handles file uploads via multipart form. POST /api/upload Stores files to sites/<site>/files/<YYYY>/<MM>/<filename>.

func (*Handler) HandleUserCreate 

func (h *Handler) HandleUserCreate(c *gin.Context)

HandleUserCreate creates a new user. POST /api/system/users

func (*Handler) HandleUserDelete 

func (h *Handler) HandleUserDelete(c *gin.Context)

HandleUserDelete deletes a user and their sessions. DELETE /api/system/users/:name

func (*Handler) HandleUserGet 

func (h *Handler) HandleUserGet(c *gin.Context)

HandleUserGet returns a single user by name (ULID). GET /api/system/users/:name

func (*Handler) HandleUserList 

func (h *Handler) HandleUserList(c *gin.Context)

HandleUserList returns all users for the current site. GET /api/system/users

func (*Handler) HandleUserResetPassword 

func (h *Handler) HandleUserResetPassword(c *gin.Context)

HandleUserResetPassword sets a new password for a user and invalidates all their sessions. POST /api/system/users/:name/reset-password

func (*Handler) HandleUserUpdate 

func (h *Handler) HandleUserUpdate(c *gin.Context)

HandleUserUpdate updates a user's profile fields. PUT /api/system/users/:name

func (*Handler) HandleWorkflowAction 

func (h *Handler) HandleWorkflowAction(c *gin.Context)

HandleWorkflowAction handles POST /api/resource/{doctype}/{name}/workflow_action

type Meta 

type Meta struct {
	ConfigVersion int    `json:"config_version,omitempty"`
	DocType       string `json:"doctype,omitempty"`
	Total         int    `json:"total,omitempty"`
}

Meta holds response metadata.

type ModuleGroup 

type ModuleGroup struct {
	Module   string           `json:"module"`
	Label    string           `json:"label"`
	DocTypes []DocTypeNavItem `json:"doctypes"`
}

ModuleGroup is a group of DocTypes under a module. 

type NavigationResponse struct {
	Modules  []ModuleGroup `json:"modules"`
	Branding Branding      `json:"branding"`
	User     UserInfo      `json:"user"`
}

NavigationResponse is the full navigation config for the SPA sidebar.

type ReferenceInfo 

type ReferenceInfo struct {
	Doctype   string `json:"doctype"`
	Fieldname string `json:"fieldname"`
	Label     string `json:"label"`
}

ReferenceInfo describes a doctype that links to the current doctype via a Link field.

type Response 

type Response struct {
	Data any   `json:"data,omitempty"`
	Meta *Meta `json:"meta,omitempty"`
}

Response is the standard API response envelope.

type SecretEntry 

type SecretEntry struct {
	KeyName   string `json:"key_name"`
	UpdatedAt string `json:"updated_at"`
}

SecretEntry represents a secret in list responses (value never exposed).

type SystemDoctypeResponse 

type SystemDoctypeResponse struct {
	DocType      *doctype.DocType             `json:"doctype"`
	Workflow     *WorkflowResponse            `json:"workflow,omitempty"`
	Permissions  map[string]bool              `json:"permissions"`
	Transitions  []doctype.WorkflowTransition `json:"transitions,omitempty"`
	ReferencedBy []ReferenceInfo              `json:"referenced_by,omitempty"`
}

SystemDoctypeResponse is the full schema response for a single DocType.

type UserInfo 

type UserInfo struct {
	Name     string   `json:"name"`
	FullName string   `json:"full_name"`
	Email    string   `json:"email"`
	Roles    []string `json:"roles"`
}

UserInfo is the current user's public info for the UI.

type UserRequest 

type UserRequest struct {
	Email    string   `json:"email"`
	Password string   `json:"password,omitempty"`
	FullName string   `json:"full_name"`
	Roles    []string `json:"roles"`
	Enabled  *bool    `json:"enabled,omitempty"`
}

UserRequest is the request body for create/update user.

type UserResponse 

type UserResponse struct {
	Name     string   `json:"name"`
	Email    string   `json:"email"`
	FullName string   `json:"full_name"`
	Roles    []string `json:"roles"`
	Enabled  bool     `json:"enabled"`
	Created  string   `json:"created"`
	Modified string   `json:"modified"`
}

UserResponse is the public representation of a user (no password_hash).

type WorkflowResponse 

type WorkflowResponse struct {
	States      []doctype.WorkflowState      `json:"states"`
	Transitions []doctype.WorkflowTransition `json:"transitions"`
	StateField  string                       `json:"state_field"`
}

WorkflowResponse holds the workflow definition for a DocType.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.