BlokeBotHelp & guides
Open the BlokeBot dashboard

Plugin development

Lua SDK

The generated module gives LuaLS type information.

SDK import

The public module provides named functions. It does not expose a generic host-call function.

  • The module provides types for parameters and results.
  • It provides types for failures and context.
  • It provides types for settings and handler input.
local blokebot = require("blokebot")

local context = blokebot.context.current()
blokebot.responses.chat("Queued for review.")

Type generation

The generator reads plugin.toml.

The generator replaces only files in its marked directory. It does not change Lua files that you own.

  1. Run blokebot-plugin generate from the project directory.
  2. Open .blokebot/lua/5.4/v1/handler-skeletons.lua.
  3. Copy the required functions into the declared author module.
  4. Implement each copied function.
  • The generator creates SDK types.
  • The generator creates plugin settings.
  • The generator creates handler types.
  • The generator creates executable no-op skeletons.

Generated type definitions

  • BlokeBotHostFailure contains a stable failure kind.
  • BlokeBotHostFailure contains a code.
  • BlokeBotHostFailure contains a safe message.
  • BlokeBotContext includes the installation context.
  • BlokeBotContext includes the channel context.
  • BlokeBotContext includes the automation context.
  • BlokeBotContext includes the migration context.
  • BlokeBotContext includes the page context.
BlokeBotContext
BlokeBotContext is a union of the context types.
BlokeBotInstallationSettings
The installation settings declared in plugin.toml for the current plugin.
BlokeBotFeatureSettings
The feature settings declared in plugin.toml for the current host feature.
BlokeBotHostFailure
The host failure value.
BlokeBotHostCancellation
The terminal cancellation value for the current call.
Plugin action input
One generated class that matches each declared page action exactly.

Host failures

A successful host function call returns its documented value. A rejected call raises a typed BlokeBotHostFailure value.

local ok, outcome = pcall(function()
  return blokebot.http.send({
    method = "GET",
    url = "https://example.invalid/item",
  })
end)

if not ok then
  blokebot.diagnostics.log("warning", outcome.safeMessage)
end

Context and settings

context.current returns the identity for the current call.

settings.installation and settings.feature return declared values for the current plugin installation or host feature. Unset optional values are absent.

  • Plugin code cannot choose a different plugin.
  • Plugin code cannot choose a different host.
  • Plugin code cannot choose a different feature.
  • Plugin code cannot choose a different actor.
  • Do not expose a protected setting in logs.
  • Do not expose a protected setting in diagnostics.
  • Do not expose a protected setting in responses.
  • Do not expose a protected setting in audit fields.
  • Do not expose a protected setting in failure messages.
  • Do not expose a protected setting in page documents.
local context = blokebot.context.current()
local settings = blokebot.settings.feature()

local message = settings["response-message"] or "Hello."
blokebot.responses.chat(message)

Lua type reference