1# plugin
  2
  3Lua-based plugin system for extending Matcha. Plugins are loaded from `~/.config/matcha/plugins/` and run inside a sandboxed Lua VM (no `os`, `io`, or `debug` libraries).
  4
  5## How it works
  6
  7The `Manager` creates a Lua VM at startup, registers the `matcha` module, and loads all plugins from the user's plugins directory. Plugins can be either a single `.lua` file or a directory with an `init.lua` entry point.
  8
  9Plugins interact with Matcha by registering callbacks on hooks:
 10
 11```lua
 12local matcha = require("matcha")
 13
 14matcha.on("email_received", function(email)
 15    matcha.log("New email from: " .. email.from)
 16    matcha.notify("New mail!", 3)
 17end)
 18```
 19
 20## Lua API (`matcha` module)
 21
 22| Function | Description |
 23|----------|-------------|
 24| `matcha.on(event, callback)` | Register a callback for a hook event |
 25| `matcha.log(msg)` | Log a message to stderr |
 26| `matcha.notify(msg [, seconds])` | Show a temporary notification in the TUI (default 2s) |
 27| `matcha.set_status(area, text)` | Set a persistent status string for a view area (`"inbox"`, `"composer"`, `"email_view"`) |
 28| `matcha.set_compose_field(field, value)` | Set a compose field value (`"to"`, `"cc"`, `"bcc"`, `"subject"`, `"body"`) |
 29| `matcha.bind_key(key, area, description, callback)` | Register a custom keyboard shortcut for a view area (`"inbox"`, `"email_view"`, `"composer"`) |
 30| `matcha.http(options)` | Make an HTTP request (see below) |
 31| `matcha.prompt(placeholder, callback)` | Open a text input overlay in the composer (see below) |
 32
 33## Hook events
 34
 35| Event | Callback argument | Description |
 36|-------|-------------------|-------------|
 37| `startup` | — | Matcha has started |
 38| `shutdown` | — | Matcha is exiting |
 39| `email_received` | Lua table with `uid`, `from`, `to`, `subject`, `date`, `is_read`, `account_id`, `folder` | New email arrived |
 40| `email_viewed` | Same as `email_received` | User opened an email |
 41| `email_send_before` | Table with `to`, `cc`, `subject`, `account_id` | About to send an email |
 42| `email_send_after` | Same as `email_send_before` | Email sent successfully |
 43| `folder_changed` | Folder name (string) | User switched folders |
 44| `composer_updated` | Table with `body`, `body_len`, `subject`, `to`, `cc`, `bcc` | Composer content changed |
 45
 46## HTTP requests
 47
 48`matcha.http(options)` makes an HTTP request and returns `(response, err)`. Options is a table with:
 49
 50- `url` (string, required) — only `http` and `https` schemes
 51- `method` (string, optional, default `"GET"`)
 52- `headers` (table, optional)
 53- `body` (string, optional)
 54
 55The response table has `status` (number), `body` (string), and `headers` (table with lowercase keys).
 56
 57Safety limits: 10s timeout, 1 MB response body cap.
 58
 59```lua
 60local res, err = matcha.http({
 61    url     = "https://api.example.com/webhook",
 62    method  = "POST",
 63    headers = { ["Content-Type"] = "application/json" },
 64    body    = '{"text":"hello"}',
 65})
 66if err then
 67    matcha.log("error: " .. err)
 68    return
 69end
 70matcha.log("status: " .. res.status)
 71```
 72
 73## User input prompts
 74
 75`matcha.prompt(placeholder, callback)` opens a text input overlay in the composer. When the user presses Enter, the callback receives their input string. Pressing Esc cancels without calling the callback.
 76
 77Only works inside a `bind_key` callback for the `"composer"` area.
 78
 79```lua
 80matcha.bind_key("ctrl+r", "composer", "rewrite", function(state)
 81    matcha.prompt("Enter instruction:", function(input)
 82        -- input is the user's text
 83        matcha.log("User typed: " .. input)
 84    end)
 85end)
 86```
 87
 88## Available plugins
 89
 90The following example plugins ship in `~/.config/matcha/plugins/`:
 91
 92- `email_age.lua`
 93- `recipient_counter.lua`
 94
 95## Files
 96
 97| File | Description |
 98|------|-------------|
 99| `plugin.go` | Plugin manager — Lua VM setup, plugin discovery and loading, notification/status state |
100| `hooks.go` | Hook definitions, callback registration, and hook invocation helpers |
101| `api.go` | `matcha` Lua module registration (`on`, `log`, `notify`, `set_status`, `set_compose_field`, `bind_key`, `http`, `prompt`) |
102| `http.go` | `matcha.http()` implementation — HTTP client with timeout and body size limits |
103| `prompt.go` | `matcha.prompt()` implementation — user input overlay for the composer |