/

Documentation / development/plugins/sdk

Plugin SDK

The public Go module is:

github.com/kumbuka-me/sdk

Most executable plugins need only the root package. It provides module registration, render request/result types, helper constructors, and typed capability clients.

Root SDK

The root package exposes helpers such as:

  • RegisterModule for a declared executable module;
  • RegisterMacro for typed macro parse/render handlers;
  • RegisterWidget for typed widget render handlers;
  • RegisterWidgetWithCommands when a widget also needs host-mediated state-changing commands;
  • RegisterContentChange for post-commit canonical Markdown change handlers;
  • RegisterExporter for typed page export handlers;
  • RegisterAdminAction for explicit administrator-triggered plugin operations;
  • Text, Markdown, and Failure for render results;
  • Pages, Drafts, Settings, Resources, Storage, Attachments, HTTP, Icon, and Log for host capabilities;
  • public wire and page/storage/attachment types used by plugin code.

The host still sanitizes resulting HTML and enforces manifest permissions. SDK helpers do not bypass runtime policy.

RegisterWidgetWithCommands keeps mutation routing in Kumbuka. A rendered widget returns an action with kind: command; when selected, the host invokes the registered command handler with the validated surface, optional current page, action ID, and current plugin features. The command may return only a safe local redirect.

RegisterContentChange receives a ContentChangeContext after changed page Markdown has been committed. The context contains public committed-page metadata and the old/new canonical source. It is intended for bounded mutation reactions such as assignment notifications; rendering never invokes it.

RegisterExporter receives an ExportContext containing public current-page metadata, stored Markdown source, and current features. It returns an ExportFile; Kumbuka validates the filename, media type, and bounded payload before serving it.

Settings and resources

Settings() reads and writes the plugin’s own simple settings namespace. A manifest can additionally declare administrator-managed typed singleton settings. Those fields are read through the same client with keys in <module>.<field> form. Kumbuka returns the manifest default until an administrator saves an explicit value, decrypts declared secret values for the owning plugin, and rejects guest writes to manifest-declared settings.

Use Resources() for repeatable admin-resource records such as repository connections, endpoints, or reusable named values. Resource schemas use host-rendered typed fields, and secret values are decrypted only for the owning plugin. Both typed settings and resources require settings:read when executable plugin code reads them.

Administrator actions

RegisterAdminAction(id, run) registers the callback for a manifest-declared admin-action module with the same ID. Kumbuka renders the button under Administration → Plugin settings, accepts the administrator POST request, and dispatches the action with the admin-action stage only while the plugin is active.

The callback has no arbitrary request or response surface: it performs the plugin-owned operation and returns an error on failure. Kumbuka retains ownership of browser authentication, administrator authorization, CSRF protection, routing, and the surrounding administration UI.

Outbound HTTP

HTTP().Do lets a plugin define a bounded HTTP(S) request while Kumbuka performs the network I/O. The plugin owns provider-specific URLs, headers, authentication, response parsing, and protocol behavior; the host owns generic limits, destination validation, redirects, TLS policy, proxy handling, and request deadlines.

The base client requires network:http. Requests that explicitly permit exact private addresses additionally require network:private, and disabling origin certificate verification additionally requires network:insecure-tls. See Capabilities for the host security model.

Markdown helpers

github.com/kumbuka-me/sdk/markdown contains small reusable Markdown parsing helpers for plugins:

  • Fence recognizes CommonMark-compatible opening backtick or tilde fences indented by at most three spaces and rejects backtick info strings containing a backtick;
  • Closes checks whether a line closes a known fence with a compatible marker run;
  • AppendFence copies a complete fenced block without interpreting its body.

Plugin-specific syntax belongs in the plugin itself rather than this helper package.

Package validation

github.com/kumbuka-me/sdk/pluginpackage exposes the public manifest and package-validation contract used by tooling and the Kumbuka host. ParseManifest strictly validates one manifest and Read validates a complete .kumbukaplugin archive. Validated package accessors return independent copies of mutable manifest slices and package bytes so callers cannot mutate cached package state.

See Package format for the archive layout and limits.