Help us shape the future of Go! Take the 2026 Go Developer Survey

sdk

package module
v0.27.2 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2026 License: Apache-2.0 Imports: 3 Imported by: 4

README

Kumbuka SDK

Go SDK and development tooling for Kumbuka plugins.

Install a plugin

  1. Download the plugin's .kumbukaplugin file.
  2. Open Administration → Plugins in Kumbuka.
  3. Upload the package and select Install and enable.

For plugin development, SDK usage, manifests, capabilities, package formats, and the wire protocol, see the Kumbuka documentation.

Plugin settings and resources

Plugins can declare boolean feature-toggle settings modules, typed singleton settings groups, and repeatable admin-resource records. Typed fields support text, textarea, URL, secret, boolean, select, and color controls. Repeatable admin resources can also use bounded list fields with typed columns for structured row editors. Kumbuka renders and validates the administrator UI, namespaces persisted values by plugin ID, and encrypts secret fields at rest.

Typed singleton settings use fields on a settings module. The owning plugin reads them through Settings().Get("<module>.<field>"); the host returns manifest defaults when no administrator value has been saved yet. Repeatable records continue to use Resources(). A plugin needs settings:read to read either form.

Outbound HTTP

Plugins that declare network:http can make bounded HTTP(S) requests with HTTP().Do. Kumbuka performs the network I/O and enforces host limits, redirect policy, destination validation, and response bounds. A plugin must additionally declare network:private before requesting an administrator-configured private IP and network:insecure-tls before disabling origin certificate verification.

The HTTP capability is intentionally generic: provider URLs, credentials, request headers, and protocol behavior belong to the plugin rather than Kumbuka core.

License

Licensed under the Apache License 2.0.

Documentation

Overview

Package sdk provides the public Go SDK for Kumbuka plugins.

Index

Constants

View Source 
const (
	// PermissionUsersRead allows plugin-safe Kumbuka user-directory lookups.
	PermissionUsersRead = "users:read"
	// PermissionNotificationsSend allows attributed in-app notification creation during mutations.
	PermissionNotificationsSend = "notifications:send"
)
View Source 
const DefaultLocale = "en"
View Source 
const Version = api.Version

Version is the Kumbuka plugin API version supported by this SDK.

Variables

This section is empty.

Functions

func Icon 

func Icon(name string, size int) (string, error)

Icon requests a host-rendered icon.

func Log 

func Log(message string) error

Log sends a bounded log entry to Kumbuka.

func PermissionFor 

func PermissionFor(method string) (string, bool)

PermissionFor returns the manifest permission required for a host capability.

func RegisterAdminAction added in v0.10.0 

func RegisterAdminAction(id string, run func() error)

RegisterAdminAction registers one explicit administrator-triggered plugin operation.

func RegisterContentChange added in v0.17.0 

func RegisterContentChange(id string, changed func(ContentChangeContext) error)

RegisterContentChange registers a handler for committed page Markdown changes.

func RegisterExporter added in v0.6.0 

func RegisterExporter(id string, export func(ExportContext) (ExportFile, error))

RegisterExporter registers one page exporter for a manifest exporter module.

func RegisterLocalizedMacro added in v0.20.0 

func RegisterLocalizedMacro[T any](id string, parse func(string) (T, bool), render func(LocalizedMacro[T]) (Result, error))

RegisterLocalizedMacro registers a macro whose renderer receives the request locale.

func RegisterMacro 

func RegisterMacro[T any](id string, parse func(string) (T, bool), render func(T) (Result, error))

RegisterMacro hides the parse/render transport and invocation serialization.

func RegisterModule 

func RegisterModule(id string, handler Handler)

RegisterModule registers a handler for a manifest module. Call during init.

func RegisterWidget added in v0.4.0 

func RegisterWidget(id string, render func(WidgetContext) (Result, error))

RegisterWidget registers a widget renderer for one manifest widget module.

func RegisterWidgetWithCommands added in v0.6.0 

func RegisterWidgetWithCommands(
	id string,
	render func(WidgetContext) (Result, error),
	command func(WidgetCommandContext) (WidgetCommandResult, error),
)

RegisterWidgetWithCommands registers a widget renderer plus host-mediated command handler.

func RenderPolicyEnabled added in v0.3.0 

func RenderPolicyEnabled(features map[string]bool, name string) bool

RenderPolicyEnabled reports whether one render-policy marker is active for a request.

func RenderPolicyFeature added in v0.3.0 

func RenderPolicyFeature(name string) string

RenderPolicyFeature returns the request feature key for one render-policy marker.

func ValidPermission 

func ValidPermission(permission string) bool

ValidPermission reports whether permission is part of the public API contract.

func ValidRenderPolicy 

func ValidRenderPolicy(name string) bool

ValidRenderPolicy reports whether name is a valid public render-policy marker.

func ValidSyntax 

func ValidSyntax(name string) bool

ValidSyntax reports whether name identifies a supported declarative Markdown grammar.

func ValidWidgetSurface added in v0.4.0 

func ValidWidgetSurface(surface string) bool

ValidWidgetSurface reports whether surface is a supported widget placement.

func ValidWidgetWidth added in v0.5.0 

func ValidWidgetWidth(width string) bool

ValidWidgetWidth reports whether width is a supported host layout hint.

Types

type Attachment 

type Attachment = api.Attachment

Attachment contains authorized attachment bytes and metadata.

type AttachmentClient 

type AttachmentClient struct {
	// contains filtered or unexported fields
}

AttachmentClient reads attachments authorized by the current request scope.

func Attachments 

func Attachments() AttachmentClient

Attachments returns the host attachment capability.

func (AttachmentClient) Read 

func (a AttachmentClient) Read(request AttachmentRead) (Attachment, error)

Read requests a bounded attachment byte range.

type AttachmentRead 

type AttachmentRead = api.AttachmentRead

AttachmentRead requests a bounded attachment range.

type CapabilityRequest 

type CapabilityRequest = api.CapabilityRequest

CapabilityRequest is the low-level host capability request envelope.

type CapabilityResponse 

type CapabilityResponse = api.CapabilityResponse

CapabilityResponse is the low-level host capability response envelope.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides typed capabilities bound to one transport.

func NewClient 

func NewClient(transport Transport) Client

NewClient creates a client. A nil transport uses the Kumbuka host.

func (Client) Attachments 

func (c Client) Attachments() AttachmentClient

Attachments returns attachment operations on this client.

func (Client) Drafts added in v0.5.0 

func (c Client) Drafts() DraftClient

Drafts returns private draft operations on this client.

func (Client) HTTP added in v0.7.0 

func (c Client) HTTP() HTTPClient

HTTP returns outbound HTTP operations on this client.

func (Client) Icon 

func (c Client) Icon(name string, size int) (string, error)

Icon renders an icon through the public host capability.

func (Client) Log 

func (c Client) Log(message string) error

Log records a host log message.

func (Client) Notifications added in v0.16.0 

func (c Client) Notifications() NotificationClient

Notifications returns in-app notification operations on this client.

func (Client) Pages 

func (c Client) Pages() PageClient

Pages returns page operations on this client.

func (Client) Resources added in v0.7.0 

func (c Client) Resources() ResourceClient

Resources returns structured settings declared by the calling plugin.

func (Client) Settings 

func (c Client) Settings() Values

Settings returns the calling plugin's settings namespace.

func (Client) Storage 

func (c Client) Storage() Values

Storage returns the calling plugin's data namespace.

func (Client) Users added in v0.16.0 

func (c Client) Users() UserClient

Users returns user-directory operations on this client.

type ContentChangeContext added in v0.17.0 

type ContentChangeContext = api.ContentChangeContext

ContentChangeContext describes one committed canonical Markdown change.

type DraftClient added in v0.5.0 

type DraftClient struct {
	// contains filtered or unexported fields
}

DraftClient provides access to the current viewer's private draft metadata.

func Drafts added in v0.5.0 

func Drafts() DraftClient

Drafts returns private draft metadata for the current viewer.

func (DraftClient) List added in v0.5.0 

func (d DraftClient) List(limit int) ([]PageDraft, error)

List returns bounded private draft metadata without editor form values.

type ExportContext added in v0.6.0 

type ExportContext = api.ExportContext

ExportContext describes one authorized page export invocation.

type ExportFile added in v0.6.0 

type ExportFile = api.ExportFile

ExportFile is one bounded file returned by an exporter plugin.

type HTTPClient added in v0.7.0 

type HTTPClient struct {
	// contains filtered or unexported fields
}

HTTPClient performs bounded outbound HTTP through Kumbuka's host network policy.

func HTTP added in v0.7.0 

func HTTP() HTTPClient

HTTP returns the bounded outbound HTTP client provided by Kumbuka.

func (HTTPClient) Do added in v0.7.0 

func (h HTTPClient) Do(request HTTPRequest) (HTTPResponse, error)

Do performs one bounded HTTP request through the Kumbuka host.

type HTTPRequest added in v0.7.0 

type HTTPRequest = api.HTTPRequest

HTTPRequest describes one bounded outbound HTTP request.

type HTTPResponse added in v0.7.0 

type HTTPResponse = api.HTTPResponse

HTTPResponse contains one bounded outbound HTTP response.

type Handler 

type Handler func(Request) Result

Handler implements a declared module's render operation.

type IconRequest 

type IconRequest = api.IconRequest

IconRequest identifies an icon to render through the host.

type LocalizedMacro added in v0.20.0 

type LocalizedMacro[T any] struct {
	// Value is the parsed macro value.
	Value T
	// Locale is the canonical interface locale selected by the host.
	Locale string
}

LocalizedMacro contains one parsed macro invocation and its request locale.

type Localizer added in v0.20.0 

type Localizer struct {
	// contains filtered or unexported fields
}

Localizer resolves plugin-owned messages for one host-selected locale.

func NewLocalizer added in v0.20.0 

func NewLocalizer(locale string, translations Translations) Localizer

NewLocalizer binds immutable plugin translations to one request locale.

func (Localizer) Locale added in v0.20.0 

func (l Localizer) Locale() string

Locale returns the effective locale used by this localizer.

func (Localizer) Text added in v0.20.0 

func (l Localizer) Text(key string) string

Text returns one translated message, falling back to English and then the key.

func (Localizer) Textf added in v0.20.0 

func (l Localizer) Textf(key string, values ...any) string

Textf formats one translated message using fmt-style placeholders.

type LogMessage 

type LogMessage = api.LogMessage

LogMessage carries one bounded plugin log entry. 

type NavigationNode = api.NavigationNode

NavigationNode is an authorized navigation entry.

type Notification added in v0.16.0 

type Notification = api.Notification

Notification is the committed notification receipt.

type NotificationClient added in v0.16.0 

type NotificationClient struct {
	// contains filtered or unexported fields
}

NotificationClient creates core-owned in-app notifications.

func Notifications added in v0.16.0 

func Notifications() NotificationClient

Notifications returns in-app notification operations.

func (NotificationClient) Send added in v0.16.0 

func (n NotificationClient) Send(input NotificationInput) (Notification, error)

Send creates one attributed in-app notification for a Kumbuka user.

type NotificationInput added in v0.16.0 

type NotificationInput = api.NotificationInput

NotificationInput describes one in-app notification.

type Page 

type Page = api.Page

Page is authorized public page metadata.

type PageClient 

type PageClient struct {
	// contains filtered or unexported fields
}

PageClient provides permission-checked page operations.

func Pages 

func Pages() PageClient

Pages returns the host page capabilities.

func (PageClient) Content 

func (p PageClient) Content(slug string) (PageContent, error)

Content reads authorized Markdown source.

func (PageClient) Favorites added in v0.5.0 

func (p PageClient) Favorites(limit int) ([]Page, error)

Favorites returns pages favorited by the current viewer.

func (PageClient) Get 

func (p PageClient) Get(slug string) (Page, error)

Get returns authorized metadata for a canonical page slug. 

func (p PageClient) Links(slug string) (PageLinks, error)

Links returns authorized incoming and outgoing wiki-link relationships.

func (PageClient) Navigation 

func (p PageClient) Navigation() ([]NavigationNode, error)

Navigation returns the prepared navigation tree.

func (PageClient) Popular added in v0.5.0 

func (p PageClient) Popular(limit int) ([]Page, error)

Popular returns the most viewed authorized pages.

func (PageClient) Recent added in v0.5.0 

func (p PageClient) Recent(limit int) ([]Page, error)

Recent returns the newest authorized pages.

func (PageClient) RecentEdited added in v0.5.0 

func (p PageClient) RecentEdited(limit int) ([]RecentEdit, error)

RecentEdited returns pages most recently edited by the current viewer.

func (PageClient) RecentViewed added in v0.5.0 

func (p PageClient) RecentViewed(limit int) ([]Page, error)

RecentViewed returns pages most recently viewed by the current viewer.

func (PageClient) Revisions added in v0.4.0 

func (p PageClient) Revisions(query RevisionQuery) (RevisionHistory, error)

Revisions returns bounded public revision metadata for one authorized page.

func (PageClient) Search 

func (p PageClient) Search(query PageQuery) ([]Page, error)

Search returns authorized pages matching a bounded query.

func (PageClient) UpdateContent added in v0.21.0 

func (p PageClient) UpdateContent(update PageContentUpdate) (PageContent, error)

UpdateContent replaces one page's Markdown body through the host's normal authorized, revisioned, optimistic-concurrency write path.

type PageContent 

type PageContent = api.PageContent

PageContent is authorized Markdown source.

type PageContentUpdate added in v0.21.0 

type PageContentUpdate = api.PageContentUpdate

PageContentUpdate replaces one page body with optimistic concurrency.

type PageDraft added in v0.5.0 

type PageDraft = api.PageDraft

PageDraft is bounded private draft metadata for the current viewer. 

type PageLink = api.PageLink

PageLink is one outgoing wiki-link relationship. 

type PageLinks = api.PageLinks

PageLinks contains incoming and outgoing page links.

type PageListQuery added in v0.5.0 

type PageListQuery = api.PageListQuery

PageListQuery selects a bounded page/activity list.

type PageQuery 

type PageQuery = api.PageQuery

PageQuery is a bounded page search query.

type PageRef 

type PageRef = api.PageRef

PageRef identifies one page for a capability request.

type Part 

type Part = api.RenderPart

Part is literal intermediate output or Markdown rendered by Kumbuka.

type PluginResourceListRequest added in v0.7.0 

type PluginResourceListRequest = api.PluginResourceListRequest

PluginResourceListRequest selects all records from one structured plugin setting resource.

type PluginResourceRecord added in v0.7.0 

type PluginResourceRecord = api.PluginResourceRecord

PluginResourceRecord contains one structured plugin setting record.

type PluginResourceRequest added in v0.7.0 

type PluginResourceRequest = api.PluginResourceRequest

PluginResourceRequest selects one structured plugin setting record.

type Property 

type Property = api.Property

Property is one public page metadata property.

type RecentEdit added in v0.5.0 

type RecentEdit = api.RecentEdit

RecentEdit is public metadata for one recent edit.

type RenderPart 

type RenderPart = api.RenderPart

RenderPart is one wire-level render output fragment.

type RenderRequest 

type RenderRequest = api.RenderRequest

RenderRequest is the wire-level render request used by the Kumbuka host.

type RenderResult 

type RenderResult = api.RenderResult

RenderResult is the wire-level render result used by the Kumbuka host.

type Request 

type Request = api.RenderRequest

Request is a render invocation supplied by Kumbuka.

type ResourceClient added in v0.7.0 

type ResourceClient struct {
	// contains filtered or unexported fields
}

ResourceClient reads structured plugin settings declared as admin resources.

func Resources added in v0.7.0 

func Resources() ResourceClient

Resources returns manifest-declared structured settings owned by this plugin.

func (ResourceClient) Get added in v0.7.0 

func (r ResourceClient) Get(resource, key string) (PluginResourceRecord, error)

Get returns one configured resource record, including decrypted secret fields.

func (ResourceClient) List added in v0.7.0 

func (r ResourceClient) List(resource string) ([]PluginResourceRecord, error)

List returns configured records for one resource in deterministic key order.

type Result 

type Result = api.RenderResult

Result contains intermediate output returned to Kumbuka.

func Dispatch 

func Dispatch(request Request) (result Result)

Dispatch runs a registered handler. It also supports native unit tests without WASM.

func Failure 

func Failure(err error) Result

Failure returns a render error.

func Markdown 

func Markdown(source string) Result

Markdown asks Kumbuka to render a nested Markdown fragment.

func Text 

func Text(text string) Result

Text returns literal intermediate output; Kumbuka still applies its sanitizer.

type Revision added in v0.4.0 

type Revision = api.Revision

Revision is public page revision metadata.

type RevisionHistory added in v0.4.0 

type RevisionHistory = api.RevisionHistory

RevisionHistory contains bounded revision metadata and the total count.

type RevisionQuery added in v0.4.0 

type RevisionQuery = api.RevisionQuery

RevisionQuery selects bounded page revision metadata.

type StorageValue 

type StorageValue = api.StorageValue

StorageValue carries a plugin storage key and optional value.

type StoredValue 

type StoredValue = api.StoredValue

StoredValue distinguishes an absent key from an empty value.

type Translations added in v0.20.0 

type Translations map[string]map[string]string

Translations contains messages by canonical locale and message key.

type Transport 

type Transport func(method string, params, result any) error

Transport enables native tests to supply fake host capabilities. Production clients use Kumbuka's WASM transport; permissions remain enforced by the host.

type User added in v0.16.0 

type User = api.User

User is plugin-safe Kumbuka user identity.

type UserClient added in v0.16.0 

type UserClient struct {
	// contains filtered or unexported fields
}

UserClient provides plugin-safe Kumbuka user-directory operations.

func Users added in v0.16.0 

func Users() UserClient

Users returns the plugin-safe Kumbuka user directory.

func (UserClient) ResolveMention added in v0.16.0 

func (u UserClient) ResolveMention(mention string) (User, error)

ResolveMention resolves an @-prefixed mention to one enabled user.

func (UserClient) Search added in v0.16.0 

func (u UserClient) Search(query UserQuery) ([]User, error)

Search returns enabled users matching a canonical mention or display name.

type UserMention added in v0.16.0 

type UserMention = api.UserMention

UserMention resolves one Kumbuka mention.

type UserQuery added in v0.16.0 

type UserQuery = api.UserQuery

UserQuery describes a bounded user-directory search.

type Values 

type Values struct {
	// contains filtered or unexported fields
}

Values is the calling plugin's host-managed key/value namespace.

func Settings 

func Settings() Values

Settings returns this plugin's settings namespace.

func Storage 

func Storage() Values

Storage returns this plugin's data namespace.

func (Values) Get 

func (v Values) Get(key string) (StoredValue, error)

Get reads a key, preserving the distinction between absent and empty values.

func (Values) Set 

func (v Values) Set(key string, value []byte) error

Set writes opaque bytes. Kumbuka enforces permissions and namespace quotas.

type WidgetAction added in v0.4.0 

type WidgetAction = api.WidgetAction

WidgetAction is one safe host-rendered widget control.

type WidgetCommandContext added in v0.6.0 

type WidgetCommandContext = api.WidgetCommandContext

WidgetCommandContext describes one host-mediated widget command invocation.

type WidgetCommandResult added in v0.6.0 

type WidgetCommandResult = api.WidgetCommandResult

WidgetCommandResult controls safe host navigation after a widget command.

type WidgetContext added in v0.4.0 

type WidgetContext = api.WidgetContext

WidgetContext describes one host widget invocation.

Source Files

View all Source files

Directories

Path Synopsis
cmd
kumbuka-plugin command
Command kumbuka-plugin develops Go plugins for Kumbuka's WASI runtime.
 Command kumbuka-plugin develops Go plugins for Kumbuka's WASI runtime.
internal
api
Package api contains the versioned wire types shared by Kumbuka and WASM plugins.
 Package api contains the versioned wire types shared by Kumbuka and WASM plugins.
build
Package build implements development-time validation and standard Go/WASI packaging.
 Package build implements development-time validation and standard Go/WASI packaging.
cli
Package cli implements the kumbuka-plugin command.
 Package cli implements the kumbuka-plugin command.
Package markdown provides reusable Markdown parsing helpers for Kumbuka plugins.
 Package markdown provides reusable Markdown parsing helpers for Kumbuka plugins.
Package pluginpackage reads bounded, versioned .kumbukaplugin ZIP archives.
 Package pluginpackage reads bounded, versioned .kumbukaplugin ZIP archives.

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.