# Lumio Extension Platform

> Build widgets, overlays, bot modules, integrations, and themes for the
> Lumio streaming platform. Extensions run sandboxed in iframes, communicate
> via @zaflun/lumio-protocol, and can persist data through server functions.
>
> npm packages: @zaflun/lumio-sdk (components + hooks), @zaflun/lumio-cli
> (dev toolchain), @zaflun/lumio-protocol (wire format),
> @zaflun/lumio-extension-types (TypeScript types)

---

## Lumio Extension Platform

# Lumio Extension Platform

Build widgets, overlays, bot modules, integrations, and themes for the Lumio streaming platform. Extensions run sandboxed in iframes, communicate via `@zaflun/lumio-protocol`, and can persist data through server functions.

## What you can build

| Category | Description | Example |
|----------|-------------|---------|
| **Widget** | Standalone visual element for stream overlays | Sports scoreboard, countdown timer |
| **Overlay** | Full-screen transparent layer for streams | Custom alert animations |
| **Bot Module** | Server-side chat command handler | Trivia game, loyalty points |
| **Integration** | External service connector | Discord webhook relay |
| **Theme** | Visual style pack for overlays | Neon cyberpunk theme |

## Architecture

```text
Developer Workflow:
  lumio login -> lumio init -> lumio dev -> lumio build -> lumio deploy

Runtime:
  Extension Bundle (HTML/JS/CSS) -> iframe Sandbox in Overlay/Dashboard
  Extension Server Functions -> Lumio API -> Isolated DB + Redis

Distribution:
  Extension Store (Browse, Install, Rate, Purchase)
  Developer Dashboard (Analytics, Revenue, Payouts)
```

## Quick links

- [Becoming a Developer](/getting-started/becoming-a-developer) — Apply for developer access
- [Quickstart](/getting-started/quickstart) — Hello World in 5 minutes
- [SDK Reference](/api-reference/sdk-client) — All hooks and components
- [CLI Reference](/api-reference/cli) — All CLI commands
- [Teams](/teams/overview) — Collaborate with other developers
- [Examples](/examples/hello-world) — Working code examples
- [AI Assistant Integration](/guides/ai-assistant) — Use llms.txt with your AI coding assistant
- [llms.txt](pathname:///llms.txt) — Structured documentation index for LLMs
- [llms-full.txt](pathname:///llms-full.txt) — Full documentation in a single file

---

## Getting Started / Overview

# Overview

Lumio Extensions are sandboxed applications that run inside the Lumio platform. They use React for UI, communicate with the host via `postMessage`, and can define server-side functions for data persistence and external API calls.

## Three surfaces

Every extension can render on up to three surfaces:

| Surface | File | Where it renders | Purpose |
|---------|------|-----------------|---------|
| **Editor** | `src/editor.tsx` | Dashboard overlay editor sidebar | Configuration UI, settings panels |
| **Layer** | `src/layer.tsx` | Browser Source (transparent) | Visual overlay in the stream |
| **Interactive** | `src/interactive.tsx` | Standalone page (`/ext/{slug}`) | Audience interaction (votes, games) |

All three surfaces share the same storage via `useExtensionStorage()` — a change in the editor propagates to the layer in real time.

## Server functions

Extensions can optionally define server-side functions that run on the Lumio API:

- **Declarative** — `queryRows`, `insertRow`, `patchRow`, `deleteRow` transpile directly to SQL (no JS runtime overhead)
- **Handler-based** — `query()`, `mutation()`, `action()` run in a V8 isolate sandbox with memory and CPU limits

Server functions get their own isolated PostgreSQL schema (`ext_{extension_id}`) and Redis namespace (`lumio:ext:{extension_id}:{account_id}:*`).

## Security model

Extensions are sandboxed at 9 layers: admin code review, DB isolation, iframe sandbox, egress allowlist, rate limiting, V8 sandbox, token scoping, Redis isolation, and secret isolation. See [Security](/account/security) for details.

## SDK

The `@zaflun/lumio-sdk` package provides React hooks and components:

- **14 components** — layout, input, and display primitives
- **10 hooks** — storage, events, actions, identity, config, theme, queries, mutations
- **Server exports** — schema definitions, declarative CRUD, handler-based functions

## Distribution

Extensions are distributed through the Lumio Extension Store. The publishing workflow is: `lumio deploy` (draft) → submission wizard → admin review → testing phase → publish.

---

## Getting Started / Becoming a Developer

# Becoming a Developer

To build and publish extensions on Lumio, you need an approved developer profile. This page walks through the application process.

## Prerequisites

- A Lumio account (sign up at [lumio.vision](https://lumio.vision))
- A personal profile (not an account/team profile)

## Applying for developer access

### 1. Navigate to the developer page

Log in to [lumio.vision](https://lumio.vision) and switch to your **Personal Profile** if you are currently viewing an account. Open **Account > Developer** from the sidebar.

### 2. Open the application wizard

Click **Apply as Developer** to launch the 4-step wizard. If a previous application was rejected, you see the rejection reason and a **Reapply** button instead.

### 3. Complete the wizard

#### Step 1: Type

Choose between two developer modes:

| Type | Description |
|------|-------------|
| **Solo** | You develop extensions independently under your own profile |
| **Team** | You plan to collaborate with others. A team is created alongside your developer profile |

You can always create or join additional teams later, regardless of which type you choose here.

#### Step 2: Profile

Fill in your developer identity:

| Field | Required | Description |
|-------|----------|-------------|
| **Display Name** | Yes | Public name shown on the Extension Store |
| **Slug** | Yes | URL-safe identifier (3-50 characters, lowercase letters, numbers, hyphens). Auto-generated from display name, editable. Appears in URLs like `lumio.vision/store/developers/{slug}` |
| **Description** | Yes | Short bio describing you or your project |
| **Motivation** | Yes | Why you want to build on Lumio |
| **What to Build** | Yes | What extensions you plan to create |

#### Step 3: Links (optional)

Provide additional context to help reviewers evaluate your application:

| Field | Description |
|-------|-------------|
| **GitHub URL** | Link to your GitHub profile or a relevant repository |
| **Website URL** | Personal or project website |
| **Experience** | Free-text description of your development experience |

All fields in this step are optional, but filling them in strengthens your application.

#### Step 4: Review

A summary of everything you entered. Verify the details are correct, then click **Submit Application**.

### 4. Wait for approval

After submission, your application enters the **pending** state. The Lumio team reviews applications manually. You receive an email notification when your application is approved or rejected.

While pending, the developer page shows a summary card with your submitted information and a "pending" badge.

## After approval

Once approved:

- The **Extensions** sidebar section appears in your dashboard
- You can run `lumio login` and `lumio init` in the CLI to scaffold your first extension
- You can create and manage [developer teams](/teams/overview)
- The developer page shows a green "approved" card with a link to the extensions dashboard

## If rejected

If your application is rejected, the developer page shows the rejection reason provided by the reviewer. You can update your application and reapply by clicking **Reapply**, which opens the wizard with your previous answers pre-filled.

## Next steps

- [Quickstart](/getting-started/quickstart) -- build your first extension in 5 minutes
- [Teams](/teams/overview) -- collaborate with other developers
- [Prerequisites](/getting-started/prerequisites) -- tools and knowledge needed

---

## Getting Started / Quickstart

# Quickstart

Build and run your first Lumio extension in 5 minutes.

## 0. Apply as a developer

Before using the CLI, you need an approved developer profile. If you have not applied yet, follow the steps in [Becoming a Developer](/getting-started/becoming-a-developer) to submit your application and wait for approval. The `lumio init` command requires an approved developer profile to create extensions.

## 1. Install the CLI

```bash
npm install -g @zaflun/lumio-cli
```

## 2. Log in to Lumio

```bash
lumio login
```

This opens your browser for PKCE OAuth authentication. After login, credentials are stored in `~/.lumio/credentials`.

For non-interactive environments, the CLI can also store a pre-provisioned Lumio API token:

```bash
lumio login --token lm_usr_your_api_key_here
```

## 3. Scaffold a new extension

```bash
lumio init my-first-extension
```

The interactive wizard asks:

```text
? Extension name: My First Extension
? Description: A hello world extension
? Category: widget
? Targets: editor, layer
? Server functions: no
```

This creates the extension on Lumio (generating an Extension-ID), scaffolds the project, and writes `lumio.config.json`.

## 4. Set up AI assistant (optional)

If you use an AI coding assistant (Claude Code, Copilot, Cursor, Gemini, Windsurf, Codex), install the Lumio skill files so your assistant understands the SDK:

```bash
npx @zaflun/lumio-agent-skill add
```

This creates `.lumio/skills/` with reference docs that teach your assistant about components, hooks, server functions, and CLI commands. See [AI Assistant Integration](/guides/ai-assistant) for per-tool setup.

## 5. Start the dev server

```bash
cd my-first-extension
pnpm install
lumio dev
```

This starts a Vite dev server with hot-reload and a Lumio sandbox that simulates the host environment with mock events.

## 6. Edit the extension

Open `src/editor.tsx`:

```tsx
import { Lumio, CompactView, TextField, Toggle, useExtensionStorage } from "@zaflun/lumio-sdk";

function Settings() {
  const [storage, setStorage] = useExtensionStorage();
  return (
    <CompactView title="My First Extension">
      <Toggle
        label="Visible"
        checked={storage.visible ?? false}
        onChange={(checked) => setStorage({ ...storage, visible: checked })}
      />
      <TextField
        label="Message"
        value={storage.text ?? ""}
        onChange={(value) => setStorage({ ...storage, text: value })}
      />
    </CompactView>
  );
}

Lumio.render(<Settings />, { target: "editor" });
```

Open `src/layer.tsx`:

```tsx
import { Lumio, Text, useExtensionStorage } from "@zaflun/lumio-sdk";

function Overlay() {
  const [storage] = useExtensionStorage();
  if (!storage.visible) return null;
  return <Text content={storage.text ?? "Hello World"} variant="heading" />;
}

Lumio.render(<Overlay />, { target: "layer" });
```

Changes in the editor surface propagate to the layer in real time.

## 7. Build and deploy

```bash
lumio build
lumio deploy -v 1.0.0 -d "Initial release"
```

Your extension is now uploaded as a draft. Use the [submission wizard](/publishing/submission-wizard) in the dashboard to submit it for review.

> **AI-Assisted Development:**
> Building with an AI coding assistant? Feed it the full Lumio documentation in one go:
> 
> - **[llms.txt](https://developers.lumio.vision/llms.txt)** — structured index of all documentation pages
> - **[llms-full.txt](https://developers.lumio.vision/llms-full.txt)** — complete documentation in a single file
> 
> Paste the URL or content into your assistant's context for accurate Lumio extension help.
> For deeper integration, install the [`@zaflun/lumio-agent-skill`](https://www.npmjs.com/package/@zaflun/lumio-agent-skill) package.
## Next steps

- [Project structure](/getting-started/project-structure) — understand every file
- [Surfaces](/surfaces/overview) — learn about the three rendering targets
- [SDK hooks](/api-reference/sdk-client) — all available hooks and components
- [Server functions](/server-functions/overview) — add data persistence

---

## Getting Started / Prerequisites

# Prerequisites

## Required

| Requirement | Minimum Version | Notes |
|-------------|----------------|-------|
| **Node.js** | 22.13+ | LTS recommended. Check with `node --version` |
| **pnpm** or **npm** | pnpm 9+ / npm 10+ | pnpm recommended for workspace features |
| **Lumio account** | — | Sign up at [lumio.vision](https://lumio.vision) |
| **React** | 18.0+ or 19.0+ | Both major versions supported |
| **TypeScript** | 5.0+ | Extensions are written in TypeScript + JSX |

## Recommended

- **VS Code** with the TypeScript and ESLint extensions
- **React Developer Tools** browser extension for debugging
- **OBS Studio** for testing layer surfaces in a real streaming environment

## Knowledge

You should be comfortable with:

- React (functional components, hooks)
- TypeScript (types, interfaces, generics)
- Basic terminal usage (npm/pnpm, command line)

No backend experience is needed for client-only extensions. For server functions, familiarity with database concepts (tables, queries) is helpful.

---

## Getting Started / Project Structure

# Project Structure

A Lumio extension project has this layout:

```text
my-extension/
+-- lumio.config.json           <- Extension manifest (required)
+-- package.json                <- Dependencies, scripts (dev/build/deploy/typecheck/lint)
+-- tsconfig.json               <- TypeScript config
+-- eslint.config.mjs           <- ESLint config (double quotes enforced)
+-- CHANGELOG.md                <- Release notes (optional, recommended)
+-- src/
|   +-- globals.css             <- Tailwind CSS entry (@import "tailwindcss") or plain CSS
|   +-- editor.tsx              <- Dashboard panel (sidebar in overlay editor)
|   +-- layer.tsx               <- Stream overlay surface (transparent)
|   +-- interactive.tsx         <- Audience page (optional)
|   +-- assets/                 <- Static assets (images, fonts, video, audio, Lottie)
|       +-- logo.png
|       +-- animation.lottie
+-- server/                     <- Optional (server: true in config)
    +-- schema.ts               <- DB schema (defineTable with validators)
    +-- functions.ts            <- Server functions (query/mutation/action)
```

> **Styling:**
> During `lumio init`, you choose your styling approach: **Tailwind CSS v4** (recommended), **plain CSS**, or **inline styles**. Tailwind extensions get `src/globals.css` with `@import "tailwindcss"` and `tailwindcss` as a dev dependency. See [lumio build](/cli/build#css-and-styling) for details.
## `lumio.config.json`

The manifest file that defines your extension. See [Configuration](/config/lumio-config) for all fields.

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extensionId": "88b2478a-39c7-468e-bebd-14e52fd97ac0",
  "name": "My Extension",
  "description": "What this extension does",
  "category": "widget",
  "version": "1.0.0",
  "targets": ["editor", "layer"],
  "server": false,
  "permissions": [],
  "visibility": "private",
  "pricing": {
    "type": "free"
  }
}
```

The `extensionId` is generated when you run `lumio init` or create the extension in the dashboard. It must be a valid UUID that exists in the Lumio database.

## `src/editor.tsx`

The editor surface renders in the dashboard overlay editor sidebar. This is where users configure your extension. Every editor file must call `Lumio.render()` within 10 seconds of page load.

## `src/layer.tsx`

The layer surface renders in Browser Sources as a transparent stream overlay. Input components (buttons, toggles, text fields) are automatically read-only on this surface.

## `src/interactive.tsx`

The interactive surface renders on a standalone page at `/ext/{slug}`. Viewers can interact with it directly (voting, playing games). This surface is optional.

## `server/schema.ts`

Defines database tables for your extension using `defineSchema` and `defineTable`. Each table gets isolated storage in `ext_{extension_id}.*` PostgreSQL schemas.

## `server/functions.ts`

Defines server functions that run on the Lumio API. Declarative functions (`queryRows`, `insertRow`, `patchRow`, `deleteRow`) transpile to SQL. Handler-based functions (`query()`, `mutation()`, `action()`) run in a V8 sandbox.

## `CHANGELOG.md`

Optional (recommended). If present, should follow the [Keep a Changelog](https://keepachangelog.com/) format. `lumio deploy` reads the entry for the deployed version and uses it as a fallback for release notes. The primary way to write release notes is the dashboard submission wizard.

---

## Surfaces / Surfaces Overview

# Surfaces

Extensions can render on three surfaces. Each surface is an independent React app that calls `Lumio.render()` with a target parameter.

| Surface | Target | File | Rendering context | Interactivity |
|---------|--------|------|--------------------|---------------|
| Editor | `"editor"` | `src/editor.tsx` | Dashboard sidebar | Full (all components) |
| Layer | `"layer"` | `src/layer.tsx` | Browser Source | Read-only (inputs disabled) |
| Interactive | `"interactive"` | `src/interactive.tsx` | Standalone page | Full (all components) |

## Shared state

All three surfaces share `useExtensionStorage()`. When the editor writes a value, the layer receives it in real time via WebSocket (`ext-storage:{install_id}` channel). This means:

- A toggle in the **editor** immediately shows/hides an element in the **layer**
- A vote cast on the **interactive page** can update a counter on the **layer** in real time
- All surfaces always read the same storage values

## Declaring targets

List the surfaces you use in `lumio.config.json`:

```json
{
  "targets": ["editor", "layer"]
}
```

Only listed targets are bundled and deployed. The interactive surface is optional — most extensions use only editor + layer.

**Valid combinations:**

| Combination | Use case |
|-------------|----------|
| `["editor"]` | Configuration-only panel with no visual output |
| `["layer"]` | Display-only overlay with no settings UI |
| `["editor", "layer"]` | Standard overlay with configuration panel (most common) |
| `["editor", "layer", "interactive"]` | Full extension with viewer interaction |
| `["editor", "interactive"]` | Audience interaction with editor config, no overlay |

## Render timeout

`Lumio.render()` must be called within **10 seconds** of page load. If the timeout expires, the extension is terminated and the user sees an error message. Avoid long async initialization before calling `Lumio.render()` — instead, render immediately with a loading state.

```tsx
// Good: render immediately, load data inside the component
function Settings() {
  const [storage] = useExtensionStorage();
  // storage is available synchronously on first render
  return <CompactView title="My Extension">...</CompactView>;
}
Lumio.render(<Settings />, { target: "editor" });

// Bad: waiting for async work before rendering
async function init() {
  await someAsyncSetup(); // may take too long!
  Lumio.render(<Settings />, { target: "editor" });
}
init();
```

## No direct DOM access

Extensions must use only SDK components. The React reconciler serializes the component tree to a JSON intermediate representation and the Lumio host renders actual DOM elements in its iframe sandbox. Direct `document.createElement()` or `document.getElementById()` calls have no effect inside the sandbox.

## Surface isolation

Each surface is rendered in its own iframe with:

- Separate JavaScript execution context
- No shared memory between surfaces
- Communication only through `useExtensionStorage()` and server functions
- Content Security Policy enforced by the host

See [Editor Panel](/surfaces/editor-panel), [Layer](/surfaces/layer), [Interactive Page](/surfaces/interactive-page), and [Shared Storage](/surfaces/shared-storage) for surface-specific documentation.

---

## Surfaces / Editor Panel

# Editor Panel

The editor surface renders in the dashboard overlay editor sidebar. It is the primary configuration UI for your extension — where streamers adjust settings, enter text, toggle features, and manage data.

## Entry point

Every extension that includes the `"editor"` target must have a `src/editor.tsx` file that calls `Lumio.render()`:

```tsx
// src/editor.tsx
import { Lumio, CompactView, TextField, Toggle, useExtensionStorage } from "@zaflun/lumio-sdk";

function Settings() {
  const [storage, setStorage] = useExtensionStorage();

  return (
    <CompactView title="Sports Scoreboard">
      <Toggle
        label="Show scores"
        checked={storage.visible ?? true}
        onChange={(checked) => setStorage({ ...storage, visible: checked })}
      />
      <TextField
        label="Home team"
        value={storage.homeTeam ?? ""}
        onChange={(value) => setStorage({ ...storage, homeTeam: value })}
      />
      <TextField
        label="Away team"
        value={storage.awayTeam ?? ""}
        onChange={(value) => setStorage({ ...storage, awayTeam: value })}
      />
    </CompactView>
  );
}

Lumio.render(<Settings />, { target: "editor" });
```

## Layout constraints

The editor panel renders inside a fixed-width sidebar (approximately **320px** wide). Follow these guidelines:

- Use `CompactView` for sections — it provides a consistent heading and padding
- Use `VStack` for vertical layouts within sections
- Avoid horizontal scrolling — content must fit within 320px
- Use `HStack` sparingly and only when the two children are very compact (e.g., a label + short input)
- Keep labels concise — long labels wrap awkwardly in the narrow sidebar

## Multiple sections

Use multiple `CompactView` components for logical groups of settings:

```tsx
import { Lumio, CompactView, VStack, TextField, NumberField, Dropdown, Toggle, useExtensionStorage } from "@zaflun/lumio-sdk";

function Settings() {
  const [storage, setStorage] = useExtensionStorage();

  return (
    <VStack>
      <CompactView title="Teams">
        <TextField
          label="Home team"
          value={storage.homeTeam ?? ""}
          onChange={(value) => setStorage({ ...storage, homeTeam: value })}
        />
        <TextField
          label="Away team"
          value={storage.awayTeam ?? ""}
          onChange={(value) => setStorage({ ...storage, awayTeam: value })}
        />
      </CompactView>

      <CompactView title="Display">
        <Dropdown
          label="Position"
          value={storage.position ?? "top-right"}
          options={[
            { value: "top-left", label: "Top left" },
            { value: "top-right", label: "Top right" },
            { value: "bottom-left", label: "Bottom left" },
            { value: "bottom-right", label: "Bottom right" },
          ]}
          onChange={(value) => setStorage({ ...storage, position: value })}
        />
        <Slider
          label="Opacity"
          min={0}
          max={100}
          value={storage.opacity ?? 100}
          onChange={(value) => setStorage({ ...storage, opacity: value })}
        />
      </CompactView>
    </VStack>
  );
}

Lumio.render(<Settings />, { target: "editor" });
```

## Configuration approaches

Three valid approaches exist for building extension settings:

### 1. `config_schema` only (no `editor.tsx`)

Define a `config_schema` in `lumio.config.json` and the host auto-generates a settings panel from the schema. No custom code needed -- the host renders each field using the same `@lumio/ui` components your `editor.tsx` would produce.

```json
{
  "config_schema": {
    "primaryColor": {
      "type": "color",
      "label": "Primary color",
      "default": "#6366f1"
    },
    "fontSize": {
      "type": "slider",
      "label": "Font size",
      "default": 16,
      "min": 8,
      "max": 72,
      "unit": "px"
    }
  }
}
```

This is the recommended approach for simple settings. See [config_schema](/config/lumio-config#config_schema) for the 17 supported field types.

### 2. `editor.tsx` only (no `config_schema`)

Build a fully custom settings UI using SDK components. Use this when you need dynamic behavior, conditional fields, server function calls, or layouts that go beyond what the schema can express.

### 3. Both `config_schema` and `editor.tsx`

When both are present, the auto-generated schema fields render first, followed by the custom editor panel below. This lets you define simple settings declaratively in the schema while adding custom interactive elements in `editor.tsx`.

### Config schema field types

The following 17 field types are supported in `config_schema`:

| Type | Description | Key properties |
|------|-------------|----------------|
| `string` | Single-line text input | `placeholder` |
| `number` | Numeric input | `min`, `max`, `step` |
| `boolean` | Toggle switch | |
| `color` | Color picker with hex input | |
| `select` | Dropdown with predefined options | `options` |
| `textarea` | Multi-line text input | `placeholder`, `rows` |
| `slider` | Range slider | `min`, `max`, `step`, `unit` |
| `font` | Font family picker (Google Fonts) | |
| `icon` | Icon picker (Lucide, emoji, emotes, uploads) | |
| `image` | Image upload or URL | |
| `sound` | Sound picker from the account's sound library | Includes extension-bundled sounds |
| `multiselect` | Multiple selection from options | `options`, `multiple` |
| `group` | Collapsible group of nested fields | `fields`, `collapsed` |
| `divider` | Visual separator (no value) | |
| `info` | Read-only informational text (no value) | `content` |
| `channel` | Multi-platform channel picker | |
| `designer` | Fullpage designer surface field | `presets` |

### `designer_schema` for fullpage design editors

Extensions that include the `"designer"` target can define a `designer_schema` in `lumio.config.json`. The designer provides a split-pane view with a live preview alongside configuration fields. Fields use the same type system as `config_schema`, but the schema is an array (with explicit `key` properties) rather than an object:

```json
{
  "targets": ["layer", "designer"],
  "designer_schema": [
    {
      "key": "layout",
      "type": "select",
      "label": "Layout",
      "default": "horizontal",
      "options": [
        { "value": "horizontal", "label": "Horizontal" },
        { "value": "vertical", "label": "Vertical" }
      ]
    },
    {
      "key": "bgColor",
      "type": "color",
      "label": "Background",
      "default": "#1a1a2e"
    }
  ]
}
```

See [lumio.config.json reference](/config/lumio-config#designer_schema) and [Targets](/config/targets) for details.

### Using `useLumioConfig` in `editor.tsx`

When building a custom editor, use the `useLumioConfig` hook with a functional updater to modify individual settings without overwriting the entire config object:

```tsx
import { useLumioConfig, EditorInput, EditorSlider } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();

  // Functional updater -- recommended for editor.tsx
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({
      ...prev,
      settings: { ...(prev.settings ?? {}), [key]: value },
    }));

  return (
    <>
      <EditorInput
        label="Title"
        value={String(config.settings?.title ?? "")}
        onChange={(v) => update("title", v)}
      />
      <EditorSlider
        label="Font Size"
        value={Number(config.settings?.fontSize ?? 16)}
        onChange={(v) => update("fontSize", v)}
        min={8}
        max={72}
        unit="px"
      />
    </>
  );
}
```

The functional updater `(prev) => next` prevents race conditions when multiple fields update concurrently.

## Available components

All SDK components work on the editor surface. Input components are **fully interactive** on this surface:

| Component | Type | Works in editor |
|-----------|------|-----------------|
| `Box` | Layout | Yes |
| `VStack` | Layout | Yes |
| `HStack` | Layout | Yes |
| `CompactView` | Layout | Yes |
| `List` | Layout | Yes |
| `Text` | Display | Yes |
| `Image` | Display | Yes |
| `Button` | Input | Yes (interactive) |
| `Toggle` | Input | Yes (interactive) |
| `TextField` | Input | Yes (interactive) |
| `TextArea` | Input | Yes (interactive) |
| `NumberField` | Input | Yes (interactive) |
| `Dropdown` | Input | Yes (interactive) |
| `Slider` | Input | Yes (interactive) |

### Editor-specific components

The SDK provides 13 additional components designed specifically for editor panels. These serialize via the Worker Reconciler and render as `@lumio/ui` components on the host side:

| Component | Description |
|-----------|-------------|
| `EditorInput` | Text, number, or color input with optional unit suffix |
| `EditorTextarea` | Multi-line text input |
| `EditorSelect` | Dropdown select with predefined options |
| `EditorCheckbox` | Toggle checkbox |
| `EditorSlider` | Range slider with optional unit |
| `EditorColorPicker` | Color picker with hex input |
| `EditorFontPicker` | Font family picker with weight and italic controls |
| `EditorFontRow` | Compact font styling row (bold, italic, weight, size, color) |
| `EditorButton` | Action button (primary, default, destructive variants) |
| `EditorGroup` | Collapsible section group |
| `EditorLabel` | Section label/heading |
| `EditorDivider` | Visual separator |
| `EditorInfo` | Informational text block |

See [Editor Components](/sdk/components/editor) for the full API reference with props and examples.

## Calling server functions

The editor can call server functions — both queries and mutations. Mutations with `editorOnly: true` can **only** be called from the editor surface; the layer and interactive surfaces cannot call them.

```tsx
import { Lumio, CompactView, Button, List, Text, useQuery, useMutation } from "@zaflun/lumio-sdk";

function RuleManager() {
  const { data: rules, refetch } = useQuery("getRules");
  const { mutate: addRule } = useMutation("addRule");
  const { mutate: deleteRule } = useMutation("deleteRule");

  return (
    <CompactView title="Challenge Rules">
      <Button
        label="Add rule"
        onClick={async () => {
          await addRule({ text: "New rule" });
          refetch();
        }}
      />
      <List
        items={(rules ?? []).map((rule) => ({
          id: rule.id,
          label: rule.text,
          action: (
            <Button
              label="Delete"
              variant="destructive"
              onClick={async () => {
                await deleteRule({ id: rule.id });
                refetch();
              }}
            />
          ),
        }))}
      />
    </CompactView>
  );
}

Lumio.render(<RuleManager />, { target: "editor" });
```

## Storage write propagation

Every call to `setStorage()` in the editor is immediately propagated to the layer and interactive surfaces via WebSocket. There is no debounce — each call triggers a storage update. For text inputs that update on every keystroke, consider debouncing in your component:

```tsx
import { useEffect, useState } from "react";
import { TextField, useExtensionStorage } from "@zaflun/lumio-sdk";

function DebouncedTextField({ storageKey }: { storageKey: string }) {
  const [storage, setStorage] = useExtensionStorage();
  const [local, setLocal] = useState(storage[storageKey] ?? "");

  useEffect(() => {
    const timer = setTimeout(() => {
      setStorage({ ...storage, [storageKey]: local });
    }, 300);
    return () => clearTimeout(timer);
  }, [local]);

  return (
    <TextField
      label="Team name"
      value={local}
      onChange={setLocal}
    />
  );
}
```

---

## Surfaces / Layer

# Layer

The layer surface renders inside Browser Sources as a **transparent overlay** on the stream. It displays visual elements that appear over the live video feed.

## Entry point

Every extension that includes the `"layer"` target must have a `src/layer.tsx` file:

```tsx
// src/layer.tsx
import { Lumio, Text, Box, useExtensionStorage } from "@zaflun/lumio-sdk";

function ScoreOverlay() {
  const [storage] = useExtensionStorage();

  if (!storage.visible) return null;

  return (
    <Box
      style={{
        position: "absolute",
        top: 20,
        right: 20,
        background: "rgba(0, 0, 0, 0.7)",
        borderRadius: 8,
        padding: 12,
      }}
    >
      <Text
        content={`${storage.homeTeam ?? "Home"} vs ${storage.awayTeam ?? "Away"}`}
        variant="heading"
      />
      <Text
        content={`${storage.homeScore ?? 0} - ${storage.awayScore ?? 0}`}
        variant="default"
      />
    </Box>
  );
}

Lumio.render(<ScoreOverlay />, { target: "layer" });
```

## Transparency

The layer renders with a **transparent background**. The Browser Source canvas is fully transparent by default — your component renders on top of the stream video feed.

- Use `position: absolute` for positioning elements anywhere on the canvas
- The layer canvas is sized to the overlay dimensions (typically 1920×1080 for 1080p streams)
- Semi-transparent backgrounds (`rgba(...)`) work for card-style overlays
- Fully transparent areas pass through to the stream video

## Read-only behavior

On the layer surface, input components are **automatically disabled** to prevent accidental interaction. They render in a read-only display mode:

| Component | Layer behavior |
|-----------|---------------|
| `Button` | Not rendered (hidden) |
| `Toggle` | Shows "On" or "Off" label text |
| `TextField` | Shows current value as plain text |
| `TextArea` | Shows current value as plain text |
| `NumberField` | Shows current value as plain text |
| `Dropdown` | Shows selected option label as plain text |
| `Slider` | Shows current numeric value as plain text |

This is automatic — you do not need to conditionally render different components for the layer surface.

## Responding to events

Use `useLumioEvent()` to react to live stream events and trigger animations or state changes:

```tsx
import { Lumio, Box, Text, useLumioEvent } from "@zaflun/lumio-sdk";
import { useState, useEffect } from "react";

function FollowerAlert() {
  const event = useLumioEvent("twitch:follower");
  const [isVisible, setIsVisible] = useState(false);
  const [followerName, setFollowerName] = useState("");

  useEffect(() => {
    if (event) {
      setFollowerName(event.data.userName);
      setIsVisible(true);
      const timer = setTimeout(() => setIsVisible(false), 5000);
      return () => clearTimeout(timer);
    }
  }, [event]);

  if (!isVisible) return null;

  return (
    <Box
      style={{
        position: "absolute",
        bottom: 80,
        left: "50%",
        transform: "translateX(-50%)",
        animation: "slideUp 0.4s ease-out",
        background: "linear-gradient(135deg, #6366f1, #8b5cf6)",
        borderRadius: 12,
        padding: "16px 24px",
      }}
    >
      <Text content={`New follower: ${followerName}`} variant="heading" />
    </Box>
  );
}

Lumio.render(<FollowerAlert />, { target: "layer" });
```

## Animations

CSS transitions and transforms are fully supported via the `style` prop:

```tsx
<Box
  style={{
    transition: "all 0.3s ease",
    transform: isVisible ? "translateY(0)" : "translateY(-20px)",
    opacity: isVisible ? 1 : 0,
  }}
>
  <Text content="Score updated!" variant="heading" />
</Box>
```

## Positioning strategy

Use `position: absolute` with `top`/`right`/`bottom`/`left` values (in pixels) to place elements. The layer canvas origin is the top-left corner:

```tsx
// Top-right corner
<Box style={{ position: "absolute", top: 20, right: 20 }}>...</Box>

// Bottom-left corner
<Box style={{ position: "absolute", bottom: 80, left: 20 }}>...</Box>

// Centered horizontally at the top
<Box style={{ position: "absolute", top: 40, left: "50%", transform: "translateX(-50%)" }}>...</Box>
```

## Performance considerations

The layer runs in an Browser Source — CPU/GPU usage affects stream quality. Keep the layer lightweight:

- Avoid heavy animations on elements that update every frame
- Use `if (!storage.visible) return null;` to skip rendering when hidden
- Prefer CSS transitions over JavaScript-driven animations
- Avoid rendering large numbers of DOM elements simultaneously

---

## Surfaces / Interactive Page

# Interactive Page

The interactive surface renders on a **standalone web page** at `/ext/{slug}` where viewers can interact with your extension — voting, playing games, submitting requests, or anything that requires direct audience participation.

## Entry point

Every extension that includes the `"interactive"` target must have a `src/interactive.tsx` file:

```tsx
// src/interactive.tsx
import { Lumio, CompactView, Button, Text, VStack, useExtensionStorage, useMutation, useQuery } from "@zaflun/lumio-sdk";

function VotingPage() {
  const [storage] = useExtensionStorage();
  const { data: results } = useQuery("getVoteResults");
  const { mutate: vote, isLoading } = useMutation("castVote");

  const total = (results?.yes ?? 0) + (results?.no ?? 0);

  return (
    <CompactView title={storage.topic ?? "Cast your vote"}>
      <VStack>
        <Text
          content={`${total} votes so far`}
          variant="muted"
        />
        <Button
          label={`Yes (${results?.yes ?? 0})`}
          onClick={() => vote({ choice: "yes" })}
          disabled={isLoading}
        />
        <Button
          label={`No (${results?.no ?? 0})`}
          onClick={() => vote({ choice: "no" })}
          disabled={isLoading}
        />
      </VStack>
    </CompactView>
  );
}

Lumio.render(<VotingPage />, { target: "interactive" });
```

## Authentication

Interactive pages use **short-lived token authentication**. The URL format is:

```
https://lumio.vision/ext/{slug}?token=lm_ext_xxxxxxxxxxxx
```

- Tokens are **15 minutes** short-lived and scoped to the specific extension installation
- The token grants read access to the installation's storage and write access to permitted server mutations
- Tokens are generated by the Lumio host and distributed to viewers (e.g., via a bot command configured in the editor)
- No cookies or session storage are used — the token is the only credential

## Full interactivity

Unlike the layer surface, the interactive surface has **full component interactivity**. All input components work as expected:

| Component | Interactive behavior |
|-----------|---------------------|
| `Button` | Clickable, triggers `onClick` |
| `Toggle` | Toggleable, triggers `onChange` |
| `TextField` | Editable text input |
| `TextArea` | Editable multi-line input |
| `NumberField` | Editable number input |
| `Dropdown` | Selectable options |
| `Slider` | Draggable range input |

## Use cases

| Use case | Example |
|----------|---------|
| **Voting** | Viewers vote on which game challenge to attempt next |
| **Predictions** | Audience predicts the outcome of a game event |
| **Song requests** | Viewers submit song requests for the streamer |
| **Chat games** | Trivia, bingo, word games driven by viewer input |
| **Challenge suggestions** | Community submits ideas for the streamer |
| **Polls** | Quick one-question audience polls |

## Sharing the link

The interactive page URL is available in the extension dashboard under the installation settings. To automatically share it in chat, request the `chat:send` permission and use `useLumioAction("chat:send")` in the editor:

```json
{
  "permissions": ["chat:send"]
}
```

## Real-time updates

The interactive page receives storage updates in real time via WebSocket, just like the layer surface. If the editor changes the voting topic, the interactive page updates immediately for all viewers already on the page:

```tsx
function VotingPage() {
  const [storage] = useExtensionStorage();
  // storage.topic updates in real time when the editor changes it

  return (
    <CompactView title={storage.topic ?? "Vote now"}>
      ...
    </CompactView>
  );
}
```

## No browser source dependency

The interactive page works independently of any browser source. Viewers access it directly in their browser — it does not require a stream overlay to be open or the stream to be live.

---

## Surfaces / Shared Storage

# Shared Storage

All three surfaces share `useExtensionStorage()`. When any surface writes to storage, all other surfaces receive the update in real time via WebSocket.

## How it works

```
Editor writes: setStorage({ visible: true })
  -> postMessage to Lumio host (iframe boundary)
  -> Lumio API: POST /v1/extension-installs/{id}/storage
  -> PostgreSQL: UPDATE storage SET value = ...
  -> Redis pub/sub: PUBLISH lumio:ext-storage:{install_id} ...
  -> WebSocket broadcast: ext-storage:{install_id} channel
  -> Layer receives: storage update event -> re-renders
  -> Interactive receives: storage update event -> re-renders
```

## Usage

```tsx
import { useExtensionStorage } from "@zaflun/lumio-sdk";

function MyComponent() {
  const [storage, setStorage] = useExtensionStorage();

  // Read a value with a default fallback
  const isVisible = storage.visible ?? false;
  const teamName = storage.homeTeam ?? "Home Team";

  // Write: always spread to preserve other keys
  const toggle = () => {
    setStorage({ ...storage, visible: !isVisible });
  };

  return (
    <Toggle label="Visible" checked={isVisible} onChange={toggle} />
  );
}
```

> **Always spread the existing storage when writing: `setStorage({ ...storage, key: value })`. Passing only `{ key: value }` **replaces the entire storage object**, deleting all other keys.:**
> 
## Storage type

The storage object is a **flat key-value store** where values can be any JSON-serializable type:

```typescript
type ExtensionStorage = Record<
  string,
  string | number | boolean | null | string[] | number[] | Record<string, unknown>
>;
```

For structured data with relations and queries, use [server functions](/server-functions/overview) instead.

## Initial value

On first load, before any data is written, `storage` is an empty object (`{}`). Always provide fallback defaults:

```tsx
// Good: provide defaults for all fields you read
const text = storage.text ?? "Default text";
const count = storage.count ?? 0;
const enabled = storage.enabled ?? true;

// Bad: assuming fields always exist (may be undefined)
const text = storage.text;
```

## Storage persistence

Storage is persisted to the database. It survives:
- Page refreshes
- Browser Source reloads
- Browser restarts
- Extension updates (unless you explicitly reset it in a mutation)

## Storage vs server functions

| | `useExtensionStorage()` | Server functions |
|---|---|---|
| **Where stored** | `ext_{id}` storage row | `ext_{id}.*` PostgreSQL tables |
| **Who can write** | Any surface | Only server function mutations |
| **Real-time sync** | Automatic (WebSocket) | Manual (call `refetch()`) |
| **Data model** | Flat key-value object | Relational tables with schema |
| **Queries** | Read entire object | Filtered, sorted, paginated rows |
| **Best for** | Settings, toggles, counters | Lists, leaderboards, complex state |

## Scoping

Storage is scoped to the **extension installation** — one record per overlay that has the extension installed. If a streamer installs your extension on two different overlays, each installation has its own independent storage.

## Storage size limit

The storage object is serialized to JSON and stored as a single database row. The maximum size is **64 KB** of serialized JSON. For larger data volumes, use server functions with `defineTable`.

## Optimistic updates

`setStorage()` applies an optimistic update — the local state updates immediately, and the network write happens asynchronously. If the network write fails, the storage reverts to the last server-confirmed value. You do not need to handle loading states for storage writes.

---

## SDK / Hooks / useLumioConfig

# useLumioConfig

Read and write the extension's user-configurable settings as defined in `config_schema` in `lumio.config.json`. Config values are persisted per installation and displayed in a dedicated settings UI separate from the main editor panel.

## Signature

```tsx
const [config, setConfig] = useLumioConfig<T>();
```

## Parameters

This hook takes no parameters.

## Return value

Returns a tuple of two values:

| Index | Type | Description |
|-------|------|-------------|
| `0` | `T` | Current config object (typed by your `config_schema`) |
| `1` | `(config: T \| (prev: T) => T) => void` | Setter function -- accepts a new config object or a functional updater |

## Example

Define the schema in `lumio.config.json`:

```json
{
  "config_schema": {
    "primaryColor": {
      "type": "string",
      "label": "Primary color",
      "default": "#6366f1"
    },
    "showAvatar": {
      "type": "boolean",
      "label": "Show avatar",
      "default": true
    },
    "fontSize": {
      "type": "number",
      "label": "Font size (px)",
      "default": 16
    }
  }
}
```

Then use it in any surface:

```tsx
import { useLumioConfig, Text, Box } from "@zaflun/lumio-sdk";

interface MyConfig {
  primaryColor: string;
  showAvatar: boolean;
  fontSize: number;
}

function AlertOverlay() {
  const [config] = useLumioConfig<MyConfig>();

  return (
    <Box
      style={{
        background: config.primaryColor,
        fontSize: config.fontSize,
      }}
    >
      <Text content="New follower!" variant="heading" />
    </Box>
  );
}
```

## Functional updater

The setter accepts a functional updater `(prev) => next`, which is the recommended pattern in `editor.tsx` to avoid overwriting concurrent changes:

```tsx
import { useLumioConfig, EditorInput, EditorSlider } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();

  // Functional updater -- recommended for editor.tsx
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({
      ...prev,
      settings: { ...(prev.settings ?? {}), [key]: value },
    }));

  return (
    <>
      <EditorInput
        label="Title"
        value={String(config.settings?.title ?? "")}
        onChange={(v) => update("title", v)}
      />
      <EditorSlider
        label="Opacity"
        value={Number(config.settings?.opacity ?? 100)}
        onChange={(v) => update("opacity", v)}
        min={0}
        max={100}
        unit="%"
      />
    </>
  );
}
```

The functional form `(prev) => next` is safer than passing a full object because it reads the latest state at update time, preventing race conditions when multiple fields update in quick succession.

## Difference from useExtensionStorage

| | `useLumioConfig` | `useExtensionStorage` |
|---|---|---|
| **Schema** | Defined in `config_schema` (typed) | Untyped key-value |
| **UI** | Auto-generated settings panel | Custom editor panel in `src/editor.tsx` |
| **Purpose** | User-facing settings (theme, preferences) | Runtime state (scores, current topic) |
| **Scope** | Per installation | Per installation |

## Notes

- The config values are initialized with defaults from `config_schema` on first install
- Changes to config trigger a re-render on all surfaces that use `useLumioConfig()`
- Config is **not** intended for high-frequency updates (use `useExtensionStorage()` for that)
- Type parameter `T` is optional but strongly recommended for type safety
- 17 field types are supported in `config_schema`: `string`, `number`, `boolean`, `color`, `select`, `textarea`, `slider`, `font`, `icon`, `image`, `sound`, `multiselect`, `group`, `divider`, `info`, `channel`, `designer` — see [lumio.config.json reference](/config/lumio-config#config_schema) for details

---

## SDK / Hooks / useLumioEvent

# useLumioEvent

Subscribe to a live stream event type. Returns the most recent event of that type, or `null` if no event has been received yet.

## Signature

```tsx
const event = useLumioEvent(eventType: LumioEventType);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `eventType` | `LumioEventType` | Yes | The event type to subscribe to (e.g. `"twitch:follower"`) |

## Return value

| Type | Description |
|------|-------------|
| `LumioEvent<T> \| null` | The most recent event of this type, or `null` before the first event |

### LumioEvent shape

```typescript
interface LumioEvent<T = unknown> {
  type: string;           // e.g. "twitch:follower"
  timestamp: string;      // ISO 8601
  data: T;                // Event-specific payload
}
```

## Supported event types

### Twitch

| Event type | Payload fields |
|------------|---------------|
| `"twitch:follower"` | `userName`, `userId`, `followedAt` |
| `"twitch:subscribe"` | `userName`, `userId`, `tier`, `months`, `message` |
| `"twitch:gift_sub"` | `gifterName`, `gifterUserId`, `recipientName`, `recipientUserId`, `tier` |
| `"twitch:resub"` | `userName`, `userId`, `tier`, `months`, `message` |
| `"twitch:cheer"` | `userName`, `userId`, `bits`, `message` |
| `"twitch:raid"` | `fromBroadcasterName`, `fromBroadcasterId`, `viewerCount` |
| `"twitch:reward"` | `userName`, `userId`, `rewardId`, `rewardTitle`, `rewardCost`, `input`, `status` |
| `"twitch:hype_train"` | `level`, `total`, `progress`, `goal` |
| `"twitch:hype_train_end"` | `level`, `total` |
| `"twitch:poll"` | `pollId`, `title`, `choices`, `status` |
| `"twitch:poll_end"` | `pollId`, `title`, `choices`, `winningChoiceId`, `status` |
| `"twitch:prediction"` | `predictionId`, `title`, `outcomes`, `status` |
| `"twitch:prediction_lock"` | `predictionId`, `title`, `outcomes` |
| `"twitch:prediction_end"` | `predictionId`, `title`, `outcomes`, `winningOutcomeId`, `status` |
| `"twitch:goal"` | `goalId`, `type`, `description`, `currentAmount`, `targetAmount` |
| `"twitch:goal_end"` | `goalId`, `type`, `description`, `currentAmount`, `targetAmount`, `isAchieved` |
| `"twitch:ad_break"` | `durationSeconds`, `startedAt` |
| `"twitch:ban"` | `userName`, `userId`, `reason`, `moderatorName` |
| `"twitch:unban"` | `userName`, `userId`, `moderatorName` |
| `"twitch:stream_online"` | `broadcasterName`, `broadcasterId`, `startedAt` |
| `"twitch:stream_offline"` | `broadcasterName`, `broadcasterId` |
| `"twitch:stream_update"` | `title`, `categoryName`, `categoryId` |

### YouTube

| Event type | Payload fields |
|------------|---------------|
| `"youtube:subscribe"` | `channelName`, `channelId` |
| `"youtube:member"` | `channelName`, `channelId`, `level` |
| `"youtube:superchat"` | `channelName`, `channelId`, `amount`, `currency`, `message` |
| `"youtube:supersticker"` | `channelName`, `channelId`, `amount`, `currency`, `stickerId` |
| `"youtube:gift_membership"` | `gifterName`, `gifterId`, `recipientCount`, `level` |
| `"youtube:gift_membership_received"` | `channelName`, `channelId`, `level` |
| `"youtube:poll"` | `question`, `choices`, `status` |

### Kick

| Event type | Payload fields |
|------------|---------------|
| `"kick:follower"` | `userName`, `userId`, `followedAt` |
| `"kick:subscribe"` | `userName`, `userId`, `months` |
| `"kick:gift"` | `gifterName`, `gifterId`, `recipientName`, `recipientUserId` |
| `"kick:stream_online"` | `broadcasterName`, `startedAt` |
| `"kick:stream_offline"` | `broadcasterName` |
| `"kick:chat"` | `userName`, `userId`, `message`, `emotes`, `badges`, `color` |

### Trovo

| Event type | Payload fields |
|------------|---------------|
| `"trovo:subscribe"` | `userName`, `userId`, `months` |
| `"trovo:spell"` | `userName`, `userId`, `spellName`, `valueMana`, `valueElixir` |
| `"trovo:chat"` | `userName`, `userId`, `message`, `emotes`, `badges` |

### Spotify

| Event type | Payload fields |
|------------|---------------|
| `"spotify:track"` | `title`, `artist`, `album`, `albumArtUrl`, `duration`, `progress`, `isPlaying` |
| `"spotify:play"` | `title`, `artist`, `progress` |
| `"spotify:pause"` | `title`, `artist`, `progress` |
| `"spotify:skip"` | `title`, `artist` |
| `"spotify:volume"` | `volume` |
| `"spotify:queue_add"` | `title`, `artist`, `addedBy` |
| `"spotify:device"` | `deviceName`, `deviceType` |
| `"spotify:playlist_add"` | `playlistId`, `playlistName`, `title`, `artist` |
| `"spotify:playlist_remove"` | `playlistId`, `playlistName`, `title`, `artist` |
| `"spotify:playlist_create"` | `playlistId`, `playlistName` |
| `"spotify:playlist_edit"` | `playlistId`, `playlistName` |
| `"spotify:playlist_delete"` | `playlistId`, `playlistName` |

### StreamElements

| Event type | Payload fields |
|------------|---------------|
| `"streamelements:tip"` | `userName`, `amount`, `currency`, `message` |

### Chat — per-platform

| Event type | Platform | Payload fields |
|------------|----------|---------------|
| `"twitch:chat"` | Twitch | `userName`, `userId`, `message`, `emotes`, `badges`, `color` |
| `"youtube:chat"` | YouTube | `userName`, `userId`, `message`, `emotes`, `badges` |
| `"kick:chat"` | Kick | `userName`, `userId`, `message`, `emotes`, `badges`, `color` |
| `"trovo:chat"` | Trovo | `userName`, `userId`, `message`, `emotes`, `badges` |

### Chat — catch-all

| Event type | Payload fields |
|------------|---------------|
| `"chat:message"` | `platform`, `userName`, `userId`, `message`, `emotes`, `badges`, `color` |

Fires for **all** connected platforms. Use this instead of per-platform chat events when platform-agnostic handling is preferred.

## Example: Follower alert

```tsx
import { Lumio, Box, Text, useLumioEvent } from "@zaflun/lumio-sdk";
import { useState, useEffect } from "react";

function FollowerAlert() {
  const event = useLumioEvent("twitch:follower");
  const [isVisible, setIsVisible] = useState(false);
  const [name, setName] = useState("");

  useEffect(() => {
    if (event) {
      setName(event.data.userName);
      setIsVisible(true);
      const timer = setTimeout(() => setIsVisible(false), 5000);
      return () => clearTimeout(timer);
    }
  }, [event]);

  if (!isVisible) return null;

  return (
    <Box
      style={{
        position: "absolute",
        bottom: 80,
        left: "50%",
        transform: "translateX(-50%)",
        background: "rgba(99, 102, 241, 0.9)",
        borderRadius: 12,
        padding: "16px 24px",
      }}
    >
      <Text content={`New follower: ${name}!`} variant="heading" />
    </Box>
  );
}

Lumio.render(<FollowerAlert />, { target: "layer" });
```

## Example: Now playing (Spotify)

```tsx
import { Box, Text, Image, useLumioEvent } from "@zaflun/lumio-sdk";

function NowPlaying() {
  const event = useLumioEvent("spotify:track");

  if (!event) return null;

  const track = event.data;

  return (
    <Box style={{ display: "flex", gap: 12, alignItems: "center" }}>
      <Image src={track.albumArtUrl} alt="Album art" style={{ width: 48, height: 48, borderRadius: 4 }} />
      <Box>
        <Text content={track.title} variant="default" />
        <Text content={track.artist} variant="muted" />
      </Box>
    </Box>
  );
}
```

## Notes

- `useLumioEvent()` returns the **latest event** each time a new one arrives — the reference changes on every new event
- Use `useEffect` with the event as a dependency to trigger side effects when a new event arrives
- The extension must have the appropriate permission to receive events (e.g., `events:read` for platform events)
- Events are only delivered when the overlay is open — missed events while offline are not replayed

---

## SDK / Hooks / useLumioAction

# useLumioAction

Execute a Lumio service action — a named operation on the host platform such as sending a chat message, changing an OBS scene, or emitting a custom event.

## Signature

```tsx
const { execute, data, isLoading, error } = useLumioAction(actionType: LumioActionType);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `actionType` | `LumioActionType` | Yes | The action type to execute (e.g. `"chat:send"`) |

## Return value

| Property | Type | Description |
|----------|------|-------------|
| `execute` | `(payload: unknown) => Promise<void>` | Call this to trigger the action |
| `data` | `unknown \| null` | Response data from the last execution |
| `isLoading` | `boolean` | `true` while the action is in progress |
| `error` | `string \| null` | Error message if the last execution failed |

## Supported action types

### Chat

| Action type | Required permission | Payload |
|-------------|--------------------|---------||
| `"chat:send"` | `chat:send` | `{ message: string }` |
| `"chat:delete"` | `chat:delete` | `{ messageId: string }` |
| `"chat:ban"` | `chat:ban` | `{ userId: string; reason?: string }` |
| `"chat:unban"` | `chat:ban` | `{ userId: string }` |
| `"chat:timeout"` | `chat:ban` | `{ userId: string; durationSeconds: number; reason?: string }` |

### OBS

| Action type | Required permission | Payload |
|-------------|--------------------|---------||
| `"obs:set_scene"` | `obs:control` | `{ scene: string }` |
| `"obs:set_source_visible"` | `obs:control` | `{ source: string; visible: boolean }` |
| `"obs:start_stream"` | `obs:control` | `{}` |
| `"obs:stop_stream"` | `obs:control` | `{}` |
| `"obs:start_recording"` | `obs:control` | `{}` |
| `"obs:stop_recording"` | `obs:control` | `{}` |

### Spotify

| Action type | Required permission | Payload |
|-------------|--------------------|---------||
| `"spotify:play"` | `spotify:control` | `{}` |
| `"spotify:pause"` | `spotify:control` | `{}` |
| `"spotify:skip"` | `spotify:control` | `{}` |
| `"spotify:seek"` | `spotify:control` | `{ positionMs: number }` |
| `"spotify:volume"` | `spotify:control` | `{ volume: number }` |
| `"spotify:shuffle"` | `spotify:control` | `{ enabled: boolean }` |
| `"spotify:repeat"` | `spotify:control` | `{ mode: "off" \| "track" \| "context" }` |
| `"spotify:queue_add"` | `spotify:control` | `{ uri: string }` |

### Events

| Action type | Required permission | Payload |
|-------------|--------------------|---------||
| `"events:emit"` | `events:write` | `{ type: string; data: unknown }` |

### Overlay

| Action type | Required permission | Payload |
|-------------|--------------------|---------||
| `"overlay:update_layer"` | `overlays:edit` | `{ layerId: string; visible: boolean }` |

## Example: Send a chat message

```tsx
import { Lumio, CompactView, Button, TextField, useLumioAction } from "@zaflun/lumio-sdk";
import { useState } from "react";

function ChatPanel() {
  const { execute: sendMessage, isLoading, error } = useLumioAction("chat:send");
  const [message, setMessage] = useState("");

  const handleSend = async () => {
    await sendMessage({ message });
    setMessage("");
  };

  return (
    <CompactView title="Send to chat">
      <TextField
        label="Message"
        value={message}
        onChange={setMessage}
      />
      {error && <Text content={error} variant="muted" />}
      <Button
        label={isLoading ? "Sending..." : "Send"}
        onClick={handleSend}
        disabled={isLoading || !message.trim()}
      />
    </CompactView>
  );
}

Lumio.render(<ChatPanel />, { target: "editor" });
```

## Example: Switch OBS scene

```tsx
import { Button, Dropdown, useLumioAction } from "@zaflun/lumio-sdk";
import { useState } from "react";

function SceneSwitcher() {
  const { execute: setScene, isLoading } = useLumioAction("obs:set_scene");
  const [scene, setSceneValue] = useState("Main");

  return (
    <>
      <Dropdown
        label="Scene"
        value={scene}
        options={[
          { value: "Main", label: "Main" },
          { value: "BRB", label: "Be Right Back" },
          { value: "Ending", label: "Ending screen" },
        ]}
        onChange={setSceneValue}
      />
      <Button
        label="Switch scene"
        onClick={() => setScene({ scene })}
        disabled={isLoading}
      />
    </>
  );
}
```

## Declaring permissions

Actions require declaring the corresponding permission in `lumio.config.json`. Undeclared permissions are rejected at runtime:

```json
{
  "permissions": ["chat:send", "obs:set_scene"]
}
```

Declared permissions are shown to the user during installation, and they must grant consent before the extension can use them.

## Notes

- Actions can only be called from the **editor** surface — not from the layer surface (read-only) and not from the interactive surface (audience-facing)
- The `error` property contains a human-readable message when an action fails (e.g., OBS is not connected)
- Each action call creates a new entry in the audit log, visible in the extension dashboard

---

## SDK / Hooks / useLumioSound

# useLumioSound

Control sound playback in browser sources from an extension. Sounds must exist in the account's sound library — either uploaded by the user or bundled with the extension.

## Signature

```tsx
const { playSound, stopSound, getSounds } = useLumioSound();
```

## Return value

| Property | Type | Description |
|----------|------|-------------|
| `playSound` | `(soundId: string, volume?: number) => Promise<void>` | Trigger playback of a sound in all subscribed browser sources |
| `stopSound` | `(soundId: string) => Promise<void>` | Stop playback of a sound in all subscribed browser sources |
| `getSounds` | `() => Promise<Sound[]>` | Fetch the list of sounds in the account's library |

### `Sound`

| Field | Type | Description |
|-------|------|-------------|
| `id` | `string` | Sound UUID |
| `name` | `string` | Display name |
| `file_size` | `number` | File size in bytes |
| `duration_ms` | `number \| null` | Duration in milliseconds |
| `created_at` | `string` | ISO-8601 upload timestamp |
| `source_extension_name` | `string \| null` | Extension that bundled this sound, or `null` for user-uploaded sounds |

## Parameters

### `playSound(soundId, volume?)`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `soundId` | `string` | Yes | UUID of the sound to play |
| `volume` | `number` | No | Playback volume 0.0–1.0 (default 1.0) |

Plays the sound in every browser source subscribed to the `sounds:{accountId}` WebSocket channel. Returns a promise that resolves when the play command is dispatched.

### `stopSound(soundId)`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `soundId` | `string` | Yes | UUID of the sound to stop |

Stops playback in all subscribed browser sources.

### `getSounds()`

Fetches the account's sound library. Returns an array of `Sound` objects. The result is not cached — call once on mount if you only need it for initial state.

## Example — play a configured sound

```tsx
import { useLumioConfig, useLumioSound, Button } from "@zaflun/lumio-sdk";

interface MyConfig {
  alertSound: string | null;
  alertVolume: number;
}

function AlertPanel() {
  const [config] = useLumioConfig<MyConfig>();
  const { playSound } = useLumioSound();

  const handlePlay = async () => {
    if (!config.alertSound) return;
    await playSound(config.alertSound, config.alertVolume ?? 1.0);
  };

  return (
    <Button onClick={handlePlay} disabled={!config.alertSound}>
      Play alert
    </Button>
  );
}
```

## Example — build a sound picker in editor.tsx

```tsx
import { useLumioConfig, useLumioSound, EditorSelect } from "@zaflun/lumio-sdk";
import { useEffect, useState } from "react";

function SoundEditor() {
  const [config, setConfig] = useLumioConfig();
  const { getSounds } = useLumioSound();
  const [sounds, setSounds] = useState([]);

  useEffect(() => {
    getSounds().then(setSounds);
  }, []);

  const options = [
    { value: "", label: "None" },
    ...sounds.map((s) => ({ value: s.id, label: s.name })),
  ];

  return (
    <EditorSelect
      label="Alert sound"
      value={config.alertSound ?? ""}
      options={options}
      onChange={(v) => setConfig((prev) => ({ ...prev, alertSound: v || null }))}
    />
  );
}
```

## Required permissions

The extension must declare `sounds:play` in `lumio.config.json` to use `playSound` and `stopSound`:

```json
{
  "permissions": ["sounds:play"]
}
```

`getSounds` does not require any declared permission — it is available to all extensions by default.

## Notes

- `playSound` and `stopSound` broadcast to **all** browser sources in the account. There is no per-surface targeting from the SDK — use the REST or GraphQL API directly if you need to target a specific overlay key.
- Sounds must exist in the account's library. If `soundId` does not exist, the server returns a 404 and the promise rejects.
- The `feature:sounds` feature flag must be enabled for the account. If it is disabled, all three methods throw a `FEATURE_DISABLED` error.

---

## SDK / Hooks / useExtensionStorage

# useExtensionStorage

Read and write the extension's shared key-value storage. Changes are persisted to the database and broadcast to all other surfaces in real time via WebSocket.

## Signature

```tsx
const [storage, setStorage] = useExtensionStorage<T>();
```

## Parameters

This hook takes no parameters.

## Return value

Returns a tuple of two values:

| Index | Type | Description |
|-------|------|-------------|
| `0` | `T` | Current storage object (defaults to `{}` on first load) |
| `1` | `(storage: T) => void` | Setter function — replaces the entire storage object |

## Example

```tsx
import { Lumio, CompactView, Toggle, TextField, useExtensionStorage } from "@zaflun/lumio-sdk";

interface MyStorage {
  visible: boolean;
  homeTeam: string;
  awayTeam: string;
  homeScore: number;
  awayScore: number;
}

function Settings() {
  const [storage, setStorage] = useExtensionStorage<MyStorage>();

  // Safely read with defaults
  const visible = storage.visible ?? true;
  const homeTeam = storage.homeTeam ?? "";

  return (
    <CompactView title="Scoreboard">
      <Toggle
        label="Show overlay"
        checked={visible}
        onChange={(checked) => setStorage({ ...storage, visible: checked })}
      />
      <TextField
        label="Home team"
        value={homeTeam}
        onChange={(value) => setStorage({ ...storage, homeTeam: value })}
      />
    </CompactView>
  );
}

Lumio.render(<Settings />, { target: "editor" });
```

## Reading in the layer

The same storage is accessible in the layer surface:

```tsx
import { Lumio, Box, Text, useExtensionStorage } from "@zaflun/lumio-sdk";

function Overlay() {
  const [storage] = useExtensionStorage<MyStorage>();

  if (!storage.visible) return null;

  return (
    <Box style={{ position: "absolute", top: 20, right: 20 }}>
      <Text content={`${storage.homeTeam} ${storage.homeScore ?? 0} - ${storage.awayScore ?? 0} ${storage.awayTeam}`} />
    </Box>
  );
}

Lumio.render(<Overlay />, { target: "layer" });
```

## Spread rule

The setter **replaces** the entire storage object. Always spread the current value:

```tsx
// Correct: preserves all other keys
setStorage({ ...storage, visible: true });

// Wrong: deletes all other keys!
setStorage({ visible: true });
```

## Real-time sync

All surfaces receive storage updates instantly via WebSocket — there is no polling. When the editor calls `setStorage()`, the layer re-renders within milliseconds.

## Persistence

Storage is persisted to PostgreSQL. It survives:
- Browser Source reloads
- Page refreshes on the interactive surface
- Extension updates (the data schema is not versioned — ensure backward compatibility when changing field names)

## Size limit

The storage object must serialize to under **64 KB** of JSON. For larger structured data, use [server functions](/server-functions/overview).

## Notes

- The type parameter `T` is optional but strongly recommended
- On first load, storage is `{}` — always use `?? defaultValue` when reading fields
- `setStorage()` applies an optimistic update locally before confirming with the server
- Storage is scoped per installation — different overlay installs of the same extension have independent storage objects

---

## SDK / Hooks / useLumioTheme

# useLumioTheme

Read the current Lumio theme (dark, light, or a custom theme). Use this to adapt your extension's appearance to match the streamer's dashboard preferences.

## Signature

```tsx
const theme = useLumioTheme();
```

## Parameters

This hook takes no parameters.

## Return value

| Type | Description |
|------|-------------|
| `LumioTheme` | The current theme object |

### LumioTheme shape

```typescript
interface LumioTheme {
  mode: "dark" | "light" | "custom";
  colors: {
    background: string;       // e.g. "#0f0f0f"
    foreground: string;       // e.g. "#ffffff"
    primary: string;          // e.g. "#6366f1"
    primaryForeground: string; // e.g. "#ffffff"
    muted: string;            // e.g. "#374151"
    mutedForeground: string;  // e.g. "#9ca3af"
    border: string;           // e.g. "#1f2937"
    card: string;             // e.g. "#111827"
    cardForeground: string;   // e.g. "#f9fafb"
  };
}
```

## Example

```tsx
import { useLumioTheme, Box, Text } from "@zaflun/lumio-sdk";

function ThemeAwareCard() {
  const theme = useLumioTheme();

  return (
    <Box
      style={{
        background: theme.colors.card,
        border: `1px solid ${theme.colors.border}`,
        borderRadius: 8,
        padding: 16,
      }}
    >
      <Text
        content="Themed content"
        style={{ color: theme.colors.foreground }}
      />
      <Text
        content="Secondary text"
        style={{ color: theme.colors.mutedForeground }}
      />
    </Box>
  );
}
```

## Adapting to dark/light mode

```tsx
import { useLumioTheme } from "@zaflun/lumio-sdk";

function AdaptiveComponent() {
  const theme = useLumioTheme();

  const shadowColor = theme.mode === "dark"
    ? "rgba(0, 0, 0, 0.5)"
    : "rgba(0, 0, 0, 0.1)";

  return (
    <Box style={{ boxShadow: `0 4px 16px ${shadowColor}` }}>
      ...
    </Box>
  );
}
```

## Notes

- The theme updates in real time if the user switches themes while the extension is open
- On the layer surface (OBS), the theme reflects the dashboard theme setting — it does not react to viewer's OS dark/light mode preference
- SDK components automatically use the current theme for their default styling — `useLumioTheme()` is for custom styling in `style` props

---

## SDK / Hooks / useIconPicker

# useIconPicker

Headless hook for building custom icon picker UIs. Manages dialog open/close state and selection.

## Signature

```tsx
const picker = useIconPicker(options?);
```

## Parameters

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `sources` | `IconSource[]` | No | Enabled sources (default: all four) |
| `onSelect` | `(icon: IconValue \| null) => void` | No | Called on selection or clear |

## Return value

| Property | Type | Description |
|----------|------|-------------|
| `isOpen` | `boolean` | Whether the picker dialog is open |
| `selected` | `IconValue \| null` | Currently selected icon |
| `open` | `() => void` | Opens the picker dialog |
| `close` | `() => void` | Closes without selecting |
| `select` | `(icon: IconValue \| null) => void` | Confirms selection and closes |
| `clear` | `() => void` | Clears selection to `null` |
| `sources` | `IconSource[]` | Active source list |

## Example

```tsx
import { Button, useIconPicker, IconDisplay } from "@zaflun/lumio-sdk";

function CustomPicker() {
  const { open, selected, clear, isOpen } = useIconPicker({
    sources: ["lucide", "emoji"],
    onSelect: (icon) => console.log("Selected:", icon),
  });

  return (
    <VStack>
      <Button label="Pick Icon" onClick={open} />
      {selected && (
        <>
          <IconDisplay icon={selected} size={48} />
          <Button label="Clear" variant="destructive" onClick={clear} />
        </>
      )}
    </VStack>
  );
}
```

---

## SDK / Hooks / useLumioIdentity

# useLumioIdentity

Access the current user and account context — who is viewing this surface, what account they belong to, and what role they hold.

## Signature

```tsx
const identity = useLumioIdentity();
```

## Parameters

This hook takes no parameters.

## Return value

| Property | Type | Description |
|----------|------|-------------|
| `userId` | `string \| null` | Lumio user ID of the current viewer, or `null` for unauthenticated interactive visitors |
| `accountId` | `string` | Lumio account ID that owns this overlay installation |
| `role` | `"owner" \| "editor" \| "viewer" \| "anonymous"` | Role of the current user in this account |
| `platform` | `string \| null` | Viewer's connected platform (e.g. `"twitch"`), or `null` |
| `platformUserId` | `string \| null` | Viewer's platform user ID, or `null` |
| `platformUserName` | `string \| null` | Viewer's platform username, or `null` |

## Example: Show different UI by role

```tsx
import { useLumioIdentity, CompactView, Text, Button } from "@zaflun/lumio-sdk";

function ConditionalEditor() {
  const identity = useLumioIdentity();

  if (identity.role === "owner" || identity.role === "editor") {
    return (
      <CompactView title="Admin controls">
        <Button label="Reset scores" onClick={() => {/* ... */}} />
      </CompactView>
    );
  }

  return (
    <CompactView title="View only">
      <Text content="You don't have permission to edit this." variant="muted" />
    </CompactView>
  );
}
```

## Example: Personalized interactive page

```tsx
import { useLumioIdentity, Text } from "@zaflun/lumio-sdk";

function PersonalizedGreeting() {
  const identity = useLumioIdentity();

  const name = identity.platformUserName ?? "viewer";

  return <Text content={`Welcome, ${name}!`} variant="heading" />;
}
```

## Identity on different surfaces

| Surface | `userId` | `role` | `platform*` |
|---------|----------|--------|-------------|
| Editor | Logged-in Lumio user | Account role | Connected platform if any |
| Layer | `null` (no viewer identity in OBS) | `"viewer"` | `null` |
| Interactive | Viewer's Lumio user ID if authenticated | `"viewer"` or `"anonymous"` | Platform if connected |

## Notes

- On the interactive surface, `userId` is `null` for unauthenticated visitors (token-only access without Lumio account login)
- Use `role` for access control in the editor — do not rely on `userId` alone
- `accountId` is always set — it identifies the account that installed the extension

---

## SDK / Hooks / useQuery

# useQuery

Call a server-side query function and return its result. The query runs once on mount and can be manually refetched.

## Signature

```tsx
const { data, isLoading, error, refetch } = useQuery<T>(functionName: string, args?: Record<string, unknown>);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `functionName` | `string` | Yes | Name of the exported server query function |
| `args` | `Record<string, unknown>` | No | Arguments to pass to the query function |

## Return value

| Property | Type | Description |
|----------|------|-------------|
| `data` | `T \| null` | Query result, or `null` while loading or on error |
| `isLoading` | `boolean` | `true` while the query is in flight |
| `error` | `string \| null` | Error message if the query failed |
| `refetch` | `() => void` | Call to re-run the query |

## Example

Define the server function in `server/functions.ts`:

```typescript
// server/functions.ts
import { queryRows } from "@zaflun/lumio-sdk/server";

export const getRules = queryRows("rules");
```

Use it in a surface:

```tsx
import { useQuery, List, Text, Button } from "@zaflun/lumio-sdk";

function RuleList() {
  const { data: rules, isLoading, error, refetch } = useQuery("getRules");

  if (isLoading) return <Text content="Loading..." variant="muted" />;
  if (error) return <Text content={`Error: ${error}`} variant="muted" />;

  return (
    <>
      <Button label="Refresh" onClick={refetch} />
      <List
        items={(rules ?? []).map((rule) => ({
          id: rule.id,
          label: rule.text,
        }))}
      />
    </>
  );
}
```

## Example with arguments

```typescript
// server/functions.ts
import { queryRows, filter, arg } from "@zaflun/lumio-sdk/server";

export const getRulesByStatus = queryRows("rules", {
  filter: filter("revealed", "=", arg("revealed")),
});
```

```tsx
const { data: revealedRules } = useQuery("getRulesByStatus", { revealed: true });
const { data: hiddenRules } = useQuery("getRulesByStatus", { revealed: false });
```

## Auto-refetch on storage change

`useQuery` does not auto-refetch when storage changes. After a mutation, call `refetch()` manually:

```tsx
const { data, refetch } = useQuery("getRules");
const { mutate: addRule } = useMutation("addRule");

const handleAdd = async () => {
  await addRule({ text: "New rule" });
  refetch(); // manually refresh the list
};
```

## Notes

- `useQuery` runs on mount automatically — no need to call anything to initiate the first load
- The query is rate limited to **100 calls per minute** per installation
- Queries are read-only — use `useMutation` for write operations
- Multiple calls to `useQuery` with the same `functionName` and `args` are **not** deduplicated — if you need shared data, lift the state up

---

## SDK / Hooks / useMutation

# useMutation

Call a server-side mutation or action function. Returns both a synchronous (`mutate`) and an async (`mutateAsync`) interface.

## Signature

```tsx
const { mutate, mutateAsync, data, isLoading, error } = useMutation<T>(functionName: string);
```

## Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `functionName` | `string` | Yes | Name of the exported server mutation or action function |

## Return value

| Property | Type | Description |
|----------|------|-------------|
| `mutate` | `(args?: Record<string, unknown>) => void` | Fire-and-forget — does not return a Promise |
| `mutateAsync` | `(args?: Record<string, unknown>) => Promise<T>` | Async variant — returns a Promise that resolves with the result |
| `data` | `T \| null` | Result of the last successful call |
| `isLoading` | `boolean` | `true` while the mutation is in flight |
| `error` | `string \| null` | Error message if the last call failed |

## Example: Simple fire-and-forget

```tsx
import { Button, useMutation } from "@zaflun/lumio-sdk";

function RevealButton({ ruleId }: { ruleId: string }) {
  const { mutate: reveal, isLoading } = useMutation("revealRule");

  return (
    <Button
      label={isLoading ? "Revealing..." : "Reveal"}
      onClick={() => reveal({ id: ruleId })}
      disabled={isLoading}
    />
  );
}
```

## Example: Async with refetch

```tsx
import { Button, useMutation, useQuery } from "@zaflun/lumio-sdk";

function AddRuleButton() {
  const { data: rules, refetch } = useQuery("getRules");
  const { mutateAsync: addRule, isLoading, error } = useMutation("addRule");

  const handleAdd = async () => {
    try {
      await addRule({ text: "New challenge rule" });
      refetch(); // refresh list after successful add
    } catch (e) {
      // error is also available as useMutation().error
      console.error("Failed to add rule:", e);
    }
  };

  return (
    <>
      {error && <Text content={error} variant="muted" />}
      <Button
        label={isLoading ? "Adding..." : "Add rule"}
        onClick={handleAdd}
        disabled={isLoading}
      />
    </>
  );
}
```

## Example: Action with external API

For handler-based `action()` functions that call external APIs:

```typescript
// server/functions.ts
import { action, v } from "@zaflun/lumio-sdk/server";

export const getScoreboard = action({
  args: { sport: v.string(), league: v.string() },
  handler: async (ctx, args) => {
    const apiKey = ctx.secrets.get("ESPN_API_KEY");
    const res = await ctx.fetch(
      `https://site.api.espn.com/apis/scoreboard?sport=${args.sport}&league=${args.league}`,
      { headers: { "Authorization": `Bearer ${apiKey}` } }
    );
    return res.json();
  },
});
```

```tsx
const { mutateAsync: fetchScores, isLoading } = useMutation("getScoreboard");

const loadScores = async () => {
  const scores = await fetchScores({ sport: "football", league: "nfl" });
  // use scores...
};
```

## editorOnly mutations

Mutations declared with `editorOnly: true` in the server function can only be called from the editor surface. Calling them from the layer or interactive surface returns an error:

```typescript
export const deleteRule = deleteRow("rules", arg("id"), { editorOnly: true });
```

## Rate limits

| Function type | Limit |
|---------------|-------|
| `mutation()` | 50 calls/minute per installation |
| `action()` | 20 calls/minute per installation |

## Notes

- `mutate()` and `mutateAsync()` both set `isLoading` and `error` on the returned object
- Only one mutation of the same name can be in flight at a time — subsequent calls queue until the previous completes
- If `mutateAsync` throws, the error is also stored in the `error` property

---

## SDK / Hooks / Bot Module Context

# Bot Module Context

The `BotModuleContext` object is passed as the first argument (`ctx`) to every bot module handler. It provides access to the database, cache, config, secrets, external HTTP, and background jobs.

## `ctx.auth` — Account context

The account (broadcaster/streamer) that installed the extension.

| Property | Type | Description |
|----------|------|-------------|
| `ctx.auth.userId` | `string \| null` | Lumio user ID of the account owner |
| `ctx.auth.accountId` | `string \| null` | Lumio account ID |
| `ctx.auth.role` | `string` | Always `"owner"` for bot module contexts |

For bot module handlers, `userId` and `accountId` are always non-null — the extension is installed on a specific account. The `string | null` type is a forward-compatibility measure.

## `ctx.user` — Chat sender

The viewer who triggered the handler. This is `null` for timer handlers and event handlers without a specific chat sender.

| Property | Type | Description |
|----------|------|-------------|
| `ctx.user.id` | `string` | Platform user ID of the sender |
| `ctx.user.name` | `string` | Username (login name) |
| `ctx.user.displayName` | `string` | Display name (may include capitalization, unicode) |
| `ctx.user.platform` | `string` | `"twitch"`, `"youtube"`, `"kick"`, `"trovo"`, or `"discord"` |
| `ctx.user.role` | `string` | `"everyone"`, `"follower"`, `"subscriber"`, `"vip"`, `"moderator"`, or `"broadcaster"` |
| `ctx.user.isMod` | `boolean` | Whether the user is a moderator |
| `ctx.user.isVip` | `boolean` | Whether the user is a VIP |
| `ctx.user.isSub` | `boolean` | Whether the user is a subscriber |

### `ctx.auth` vs `ctx.user`

| | `ctx.auth` | `ctx.user` |
|---|-----------|-----------|
| **Who** | The streamer/account owner | The viewer in chat |
| **When available** | Always | `null` for timers and some events |
| **Use case** | Account-level lookups, config | User-specific replies, permissions |

Example:

```typescript
import { command } from "@zaflun/lumio-sdk/server";

export const whoami = command("whoami", async (ctx) => {
  return {
    reply: `You are ${ctx.user.name} (${ctx.user.role}) on ${ctx.auth.accountId}'s channel`,
  };
});
```

## `ctx.config` — Resolved configuration

User-configurable settings defined in `config_schema`, with user overrides merged over extension defaults.

Config values are validated server-side against your `config_schema` before they reach the handler. You can safely access `ctx.config.myField` knowing it matches the declared type.

| Property | Type | Description |
|----------|------|-------------|
| `ctx.config` | `Record<string, unknown>` | Key-value map of resolved config values |

```typescript
export const hello = command("hello", async (ctx) => {
  const greeting = (ctx.config.greeting as string) ?? "Hello";
  const showPoints = (ctx.config.showPoints as boolean) ?? true;
  return { reply: `${greeting}, ${ctx.user.name}!` };
});
```

## `ctx.db` — Extension database

Read and write data in the extension's isolated PostgreSQL schema (`ext_{install_id}`).

| Method | Signature | Description |
|--------|-----------|-------------|
| `get` | `(table: string, id: string) => Promise<Record<string, unknown> \| null>` | Get a row by ID |
| `list` | `(table: string) => Promise<Record<string, unknown>[]>` | List all rows in a table |
| `insert` | `(table: string, row: Record<string, unknown>) => Promise<string>` | Insert a row, returns the new row ID |
| `patch` | `(table: string, id: string, row: Record<string, unknown>) => Promise<void>` | Update specific fields on a row |
| `delete` | `(table: string, id: string) => Promise<void>` | Delete a row by ID |

```typescript
// Insert a new record
const id = await ctx.db.insert("user_points", {
  user_id: ctx.user.id,
  balance: 100,
});

// Read it back
const record = await ctx.db.get("user_points", id);

// Update a field
await ctx.db.patch("user_points", id, { balance: 200 });

// List all records
const all = await ctx.db.list("user_points");

// Delete
await ctx.db.delete("user_points", id);
```

Tables must be defined in `server/schema.ts`. The extension cannot access core Lumio tables or other extensions' schemas.

## `ctx.cache` — Scoped Redis cache

Fast temporary storage backed by Redis. Keys are automatically scoped to the extension installation.

| Method | Signature | Description |
|--------|-----------|-------------|
| `get` | `(key: string) => Promise<unknown \| null>` | Read a cached value |
| `set` | `(key: string, value: unknown, ttl?: number) => Promise<void>` | Store a value (default TTL: 1 hour) |
| `delete` | `(key: string) => Promise<void>` | Remove a cached value |
| `increment` | `(key: string, by?: number) => Promise<number>` | Atomically increment a numeric value |

```typescript
await ctx.cache.set("spam_score:user123", 5, 300); // 5-minute TTL
const score = await ctx.cache.get("spam_score:user123");
await ctx.cache.increment("message_count", 1);
await ctx.cache.delete("spam_score:user123");
```

See [Cache & Background Jobs](/guides/cache-and-defer) for limits and usage patterns.

## `ctx.secrets` — Extension secrets

Read encrypted secrets stored via `lumio secrets set` or the dashboard.

| Method | Signature | Description |
|--------|-----------|-------------|
| `get` | `(key: string) => Promise<string \| null>` | Read a secret value |

```typescript
const apiKey = await ctx.secrets.get("EXTERNAL_API_KEY");
```

Secret values are never logged or included in error reports.

## `ctx.fetch` — External HTTP

Make HTTPS requests to external APIs. Only hostnames declared in the `egress.allowHosts` manifest field are permitted.

```typescript
const res = await ctx.fetch("https://api.example.com/data", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ query: "test" }),
});

const data = await res.json();
```

Restrictions:

- HTTPS only
- No private IP ranges or localhost
- Only declared `egress.allowHosts`
- Maximum 10 calls per handler invocation

## `ctx.defer()` — Background jobs

Queue a function that executes after the handler returns. The handler can respond immediately while expensive work runs in the background.

| Parameter | Type | Description |
|-----------|------|-------------|
| `fn` | `() => Promise<void>` | Async function to run in the background |

```typescript
export const points = command("points", async (ctx) => {
  const balance = (await ctx.cache.get(`pts:${ctx.user.id}`)) as number ?? 0;

  ctx.defer(async () => {
    await ctx.db.insert("point_history", {
      user_id: ctx.user.id,
      checked_at: Date.now(),
    });
  });

  return { reply: `${ctx.user.name}: ${balance} points` };
});
```

Limits: 5 deferred calls per handler, 10-second timeout each. Errors are logged but not surfaced to chat. See [Cache & Background Jobs](/guides/cache-and-defer) for details.

## Handler return types

### Command, keyword, pattern, timer, event handlers

```typescript
interface HandlerResponse {
  reply?: string;        // Text to send to chat
  actions?: ActionRequest[]; // Additional platform actions
}

interface ActionRequest {
  action: string;
  params: Record<string, unknown>;
}
```

Return `null` for silent handling (no reply, no action).

### Moderation handler

```typescript
interface ModerationResponse {
  block: boolean;           // Whether to block/delete the message
  action?: "delete" | "timeout" | "ban";
  duration?: number;        // Timeout duration in seconds
  reason?: string;          // Audit log reason
}
```

Return `{ block: false }` to allow the message through.

## Context availability by handler type

| Property | `command` | `keyword` | `pattern` | `event` | `timer` | `moderate` |
|----------|-----------|-----------|-----------|---------|---------|------------|
| `ctx.auth` | Yes | Yes | Yes | Yes | Yes | Yes |
| `ctx.user` | Yes | Yes | Yes | Depends | `null` | Yes |
| `ctx.config` | Yes | Yes | Yes | Yes | Yes | Yes |
| `ctx.db` | Yes | Yes | Yes | Yes | Yes | Yes |
| `ctx.cache` | Yes | Yes | Yes | Yes | Yes | Yes |
| `ctx.secrets` | Yes | Yes | Yes | Yes | Yes | Yes |
| `ctx.fetch` | Yes | Yes | Yes | Yes | Yes | Yes |
| `ctx.defer` | Yes | Yes | Yes | Yes | Yes | Yes |

For event handlers, `ctx.user` is populated when the event has a specific chat sender. For events like `twitch:stream_online` that have no sender, `ctx.user` is `null`.

---

## SDK / Components / Layout Components

# Layout Components

Layout components control the arrangement and grouping of other components. They do not render visible content themselves — they organize space.

## Box

A generic container element. Renders as a `div` with full `style` support.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `style` | `VisionStyle` | No | CSS style object (subset of CSS properties) |
| `children` | `ReactNode` | No | Child components |

### Example

```tsx
import { Box, Text } from "@zaflun/lumio-sdk";

function Card() {
  return (
    <Box
      style={{
        background: "rgba(0, 0, 0, 0.7)",
        borderRadius: 8,
        padding: 16,
        position: "absolute",
        top: 20,
        right: 20,
      }}
    >
      <Text content="Score: 3 - 1" variant="heading" />
    </Box>
  );
}
```

---

## VStack

A vertical stack layout. Children are arranged from top to bottom with optional spacing.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `gap` | `number` | No | Spacing between children in pixels (default: `8`) |
| `align` | `"start" \| "center" \| "end" \| "stretch"` | No | Cross-axis alignment (default: `"stretch"`) |
| `style` | `VisionStyle` | No | Additional style |
| `children` | `ReactNode` | No | Child components |

### Example

```tsx
import { VStack, Text, Button } from "@zaflun/lumio-sdk";

function ButtonGroup() {
  return (
    <VStack gap={12} align="stretch">
      <Button label="Yes" onClick={() => {}} />
      <Button label="No" onClick={() => {}} />
      <Button label="Maybe" onClick={() => {}} />
    </VStack>
  );
}
```

---

## HStack

A horizontal stack layout. Children are arranged from left to right.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `gap` | `number` | No | Spacing between children in pixels (default: `8`) |
| `align` | `"start" \| "center" \| "end" \| "baseline"` | No | Cross-axis alignment (default: `"center"`) |
| `justify` | `"start" \| "center" \| "end" \| "between" \| "around"` | No | Main-axis justification |
| `style` | `VisionStyle` | No | Additional style |
| `children` | `ReactNode` | No | Child components |

### Example

```tsx
import { HStack, Text, Image } from "@zaflun/lumio-sdk";

function ProfileRow() {
  return (
    <HStack gap={12} align="center">
      <Image src="https://example.com/avatar.png" alt="Avatar" style={{ width: 40, height: 40, borderRadius: "50%" }} />
      <Text content="StreamerName" variant="default" />
    </HStack>
  );
}
```

---

## CompactView

A titled section container for the editor panel. Renders a heading and a bordered card with padding. The standard layout building block for editor surfaces.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `title` | `string` | Yes | Section heading text |
| `children` | `ReactNode` | No | Content inside the section |
| `style` | `VisionStyle` | No | Additional style for the card container |

### Example

```tsx
import { CompactView, Toggle, TextField, useExtensionStorage } from "@zaflun/lumio-sdk";

function Settings() {
  const [storage, setStorage] = useExtensionStorage();

  return (
    <CompactView title="Display settings">
      <Toggle
        label="Show overlay"
        checked={storage.visible ?? true}
        onChange={(checked) => setStorage({ ...storage, visible: checked })}
      />
      <TextField
        label="Custom message"
        value={storage.message ?? ""}
        onChange={(value) => setStorage({ ...storage, message: value })}
      />
    </CompactView>
  );
}
```

---

## List

A vertical list of items with consistent spacing and optional action buttons per item.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `items` | `ListItem[]` | Yes | Array of list items |
| `emptyText` | `string` | No | Text to show when `items` is empty (default: `"No items"`) |
| `style` | `VisionStyle` | No | Additional style |

### ListItem shape

```typescript
interface ListItem {
  id: string;
  label: string;
  sublabel?: string;
  action?: ReactNode;  // typically a Button
}
```

### Example

```tsx
import { List, Button, useQuery, useMutation } from "@zaflun/lumio-sdk";

function RuleList() {
  const { data: rules = [] } = useQuery("getRules");
  const { mutate: deleteRule } = useMutation("deleteRule");

  return (
    <List
      emptyText="No rules yet. Add one above."
      items={rules.map((rule) => ({
        id: rule.id,
        label: rule.text,
        sublabel: rule.revealed ? "Revealed" : "Hidden",
        action: (
          <Button
            label="Delete"
            variant="destructive"
            onClick={() => deleteRule({ id: rule.id })}
          />
        ),
      }))}
    />
  );
}
```

---

## SDK / Components / Input Components

# Input Components

Input components are fully interactive on the **editor** and **interactive** surfaces. On the **layer** surface, they automatically render in a read-only display mode.

## Button

A clickable action button.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `label` | `string` | Yes | Button text |
| `onClick` | `() => void` | Yes | Click handler |
| `variant` | `"default" \| "destructive"` | No | Visual variant (default: `"default"`) |
| `disabled` | `boolean` | No | Prevents clicks and shows disabled state |
| `style` | `VisionStyle` | No | Additional style |

**Layer behavior:** Not rendered (hidden entirely).

### Example

```tsx
import { Button, useMutation } from "@zaflun/lumio-sdk";

function ActionBar() {
  const { mutate: resetScores, isLoading } = useMutation("resetScores");

  return (
    <>
      <Button
        label="Update scores"
        onClick={() => {/* ... */}}
      />
      <Button
        label="Reset all"
        variant="destructive"
        onClick={() => resetScores()}
        disabled={isLoading}
      />
    </>
  );
}
```

---

## Toggle

A boolean on/off switch with a label.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `label` | `string` | Yes | Label text |
| `checked` | `boolean` | Yes | Current state |
| `onChange` | `(checked: boolean) => void` | Yes | Change handler |
| `disabled` | `boolean` | No | Prevents interaction |
| `style` | `VisionStyle` | No | Additional style |

**Layer behavior:** Shows "On" or "Off" as plain text.

### Example

```tsx
import { Toggle, useExtensionStorage } from "@zaflun/lumio-sdk";

function VisibilityToggle() {
  const [storage, setStorage] = useExtensionStorage();

  return (
    <Toggle
      label="Show overlay"
      checked={storage.visible ?? true}
      onChange={(checked) => setStorage({ ...storage, visible: checked })}
    />
  );
}
```

---

## TextField

A single-line text input.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `label` | `string` | Yes | Input label |
| `value` | `string` | Yes | Current value |
| `onChange` | `(value: string) => void` | Yes | Change handler |
| `placeholder` | `string` | No | Placeholder text |
| `disabled` | `boolean` | No | Makes the field non-editable |
| `style` | `VisionStyle` | No | Additional style |

**Layer behavior:** Shows current value as plain text.

### Example

```tsx
import { TextField, useExtensionStorage } from "@zaflun/lumio-sdk";

function TeamInput() {
  const [storage, setStorage] = useExtensionStorage();

  return (
    <TextField
      label="Home team"
      value={storage.homeTeam ?? ""}
      placeholder="Enter team name"
      onChange={(value) => setStorage({ ...storage, homeTeam: value })}
    />
  );
}
```

---

## TextArea

A multi-line text input.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `label` | `string` | Yes | Input label |
| `value` | `string` | Yes | Current value |
| `onChange` | `(value: string) => void` | Yes | Change handler |
| `placeholder` | `string` | No | Placeholder text |
| `rows` | `number` | No | Number of visible rows (default: `3`) |
| `disabled` | `boolean` | No | Makes the field non-editable |
| `style` | `VisionStyle` | No | Additional style |

**Layer behavior:** Shows current value as plain text.

### Example

```tsx
import { TextArea, useExtensionStorage } from "@zaflun/lumio-sdk";

function NotesInput() {
  const [storage, setStorage] = useExtensionStorage();

  return (
    <TextArea
      label="Stream notes"
      value={storage.notes ?? ""}
      placeholder="Add notes for your stream..."
      rows={4}
      onChange={(value) => setStorage({ ...storage, notes: value })}
    />
  );
}
```

---

## NumberField

A numeric input with increment/decrement buttons.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `label` | `string` | Yes | Input label |
| `value` | `number` | Yes | Current value |
| `onChange` | `(value: number) => void` | Yes | Change handler |
| `min` | `number` | No | Minimum value |
| `max` | `number` | No | Maximum value |
| `step` | `number` | No | Increment step (default: `1`) |
| `disabled` | `boolean` | No | Makes the field non-editable |
| `style` | `VisionStyle` | No | Additional style |

**Layer behavior:** Shows current value as plain text.

### Example

```tsx
import { NumberField, useExtensionStorage } from "@zaflun/lumio-sdk";

function ScoreInput() {
  const [storage, setStorage] = useExtensionStorage();

  return (
    <NumberField
      label="Home score"
      value={storage.homeScore ?? 0}
      min={0}
      max={99}
      onChange={(value) => setStorage({ ...storage, homeScore: value })}
    />
  );
}
```

---

## Dropdown

A select input with a list of options.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `label` | `string` | Yes | Input label |
| `value` | `string` | Yes | Currently selected value |
| `options` | `{ value: string; label: string }[]` | Yes | Available options |
| `onChange` | `(value: string) => void` | Yes | Change handler |
| `disabled` | `boolean` | No | Prevents selection |
| `style` | `VisionStyle` | No | Additional style |

**Layer behavior:** Shows the selected option's `label` as plain text.

### Example

```tsx
import { Dropdown, useExtensionStorage } from "@zaflun/lumio-sdk";

function PositionSelector() {
  const [storage, setStorage] = useExtensionStorage();

  return (
    <Dropdown
      label="Position"
      value={storage.position ?? "top-right"}
      options={[
        { value: "top-left", label: "Top left" },
        { value: "top-right", label: "Top right" },
        { value: "bottom-left", label: "Bottom left" },
        { value: "bottom-right", label: "Bottom right" },
      ]}
      onChange={(value) => setStorage({ ...storage, position: value })}
    />
  );
}
```

---

## Slider

A range input for selecting a numeric value within a range.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `label` | `string` | Yes | Input label |
| `value` | `number` | Yes | Current value |
| `min` | `number` | Yes | Minimum value |
| `max` | `number` | Yes | Maximum value |
| `onChange` | `(value: number) => void` | Yes | Change handler |
| `step` | `number` | No | Increment step (default: `1`) |
| `showValue` | `boolean` | No | Show current value next to label (default: `true`) |
| `disabled` | `boolean` | No | Prevents interaction |
| `style` | `VisionStyle` | No | Additional style |

**Layer behavior:** Shows current numeric value as plain text.

### Example

```tsx
import { Slider, useExtensionStorage } from "@zaflun/lumio-sdk";

function OpacitySlider() {
  const [storage, setStorage] = useExtensionStorage();

  return (
    <Slider
      label="Opacity"
      value={storage.opacity ?? 100}
      min={0}
      max={100}
      step={5}
      onChange={(value) => setStorage({ ...storage, opacity: value })}
    />
  );
}
```

---

## SDK / Components / Display Components

# Display Components

Display components render content — text, images, and other read-only visual elements. They work on all three surfaces.

## Text

Renders a text string with typography variants.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `content` | `string` | Yes | Text content to display |
| `variant` | `"heading" \| "default" \| "muted"` | No | Typography preset (default: `"default"`) |
| `style` | `VisionStyle` | No | Additional style (font size, color, etc.) |

### Variants

| Variant | Description | Use case |
|---------|-------------|----------|
| `"heading"` | Bold, larger font size | Section titles, alert names |
| `"default"` | Normal body text | Primary content, scores, labels |
| `"muted"` | Dimmed, smaller font | Timestamps, secondary info, help text |

### Example

```tsx
import { Text, VStack } from "@zaflun/lumio-sdk";

function ScoreDisplay({ homeScore, awayScore, teamA, teamB }) {
  return (
    <VStack gap={4}>
      <Text content={`${teamA} vs ${teamB}`} variant="heading" />
      <Text content={`${homeScore} - ${awayScore}`} variant="default" />
      <Text content="Live score" variant="muted" />
    </VStack>
  );
}
```

### Custom styling

```tsx
<Text
  content="Breaking news!"
  style={{
    color: "#ef4444",
    fontWeight: 700,
    fontSize: 20,
    letterSpacing: "0.05em",
    textTransform: "uppercase",
  }}
/>
```

---

## Image

Renders an image with an accessible alt text.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `src` | `string` | Yes | Image URL (must be in the egress allowlist for external URLs) |
| `alt` | `string` | Yes | Accessible alt text |
| `objectFit` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | No | How the image fills its container (default: `"cover"`) |
| `style` | `VisionStyle` | No | Additional style (width, height, border-radius, etc.) |

### Example

```tsx
import { Image, Box, Text, useLumioEvent } from "@zaflun/lumio-sdk";

function NowPlayingCard() {
  const event = useLumioEvent("spotify:track");

  if (!event) return null;

  const track = event.data;

  return (
    <Box style={{ display: "flex", gap: 12, alignItems: "center" }}>
      <Image
        src={track.albumArtUrl}
        alt={`Album art for ${track.album}`}
        objectFit="cover"
        style={{ width: 56, height: 56, borderRadius: 6, flexShrink: 0 }}
      />
      <Box>
        <Text content={track.title} variant="default" />
        <Text content={track.artist} variant="muted" />
      </Box>
    </Box>
  );
}
```

### External images and egress

External image URLs must be in the egress allowlist in `lumio.config.json`:

```json
{
  "egress": {
    "allowHosts": ["i.scdn.co", "*.spotifycdn.com"]
  }
}
```

Internal Lumio CDN images (profile avatars, uploaded assets) do not require egress allowlist entries.

---

## IconDisplay

Renders any `IconValue` as the appropriate visual element.

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `icon` | `IconValue \| null` | Yes | The icon to render |
| `size` | `number` | No | Size in pixels (default: `24`) |
| `className` | `string` | No | CSS class for styling |

### Rendering behavior

| `icon.type` | Rendered as |
|-------------|-------------|
| `lucide` | Inline SVG (24x24 viewBox, stroke-based) |
| `emoji` | Text span with the Unicode character |
| `emote` | `<img>` with the CDN URL |
| `upload` | `<img>` with the upload URL |
| `null` | Empty placeholder |

### Example

```tsx
import { IconDisplay } from "@zaflun/lumio-sdk";
import type { IconValue } from "@zaflun/lumio-sdk";

function AlertHeader({ icon }: { icon: IconValue | null }) {
  return (
    <HStack>
      <IconDisplay icon={icon} size={32} />
      <Text>Alert!</Text>
    </HStack>
  );
}
```

---

## Display component guidelines

| Principle | Guidance |
|-----------|---------|
| **Always provide `alt` text** | Every `Image` needs a descriptive `alt` for accessibility |
| **Use `variant` before custom style** | Prefer `variant="muted"` over `style={{ color: "#9ca3af" }}` for consistency |
| **Avoid fixed font sizes in the layer** | Prefer relative units or theme-aware values to maintain readability at different canvas sizes |
| **Keep text concise** | Overlay text should be scannable at a glance — keep labels under 40 characters |

---

## SDK / Components / IconPicker

# IconPicker

A universal icon picker for extension config panels. Lets users select from Lucide icons, Unicode emojis, platform emotes, or custom uploads.

## Import

```tsx
import { IconPicker } from "@zaflun/lumio-sdk";
import type { IconValue } from "@zaflun/lumio-sdk";
```

## Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `IconValue \| null` | Yes | Current selection |
| `onChange` | `(icon: IconValue \| null) => void` | Yes | Called when the user picks or clears |
| `sources` | `IconSource[]` | No | Enabled tabs (default: all four) |
| `size` | `"sm" \| "md" \| "lg"` | No | Button size (default: `"md"`) |
| `placeholder` | `string` | No | Text shown when no icon selected |

## IconValue

All icon selections produce a universal `IconValue` object:

```typescript
interface IconValue {
  type: "lucide" | "emoji" | "emote" | "upload";
  value: string;
  label?: string;
  platform?: string;
}
```

| Type | `value` | `label` | `platform` |
|------|---------|---------|------------|
| `lucide` | Icon name (`"heart"`) | Display name | -- |
| `emoji` | Unicode character (`"😀"`) | Emoji name | -- |
| `emote` | CDN URL | Emote name | `"twitch"` \| `"7tv"` \| `"bttv"` \| `"ffz"` |
| `upload` | Upload URL | Original filename | -- |

## Sources

Control which tabs appear with the `sources` prop:

```tsx
// Only Lucide icons and emojis
<IconPicker
  value={icon}
  onChange={setIcon}
  sources={["lucide", "emoji"]}
/>
```

Available sources: `"lucide"`, `"emoji"`, `"emote"`, `"upload"`.

## Example

```tsx
import { Lumio, CompactView, IconPicker, IconDisplay, useExtensionStorage } from "@zaflun/lumio-sdk";
import type { IconValue } from "@zaflun/lumio-sdk";

interface MyConfig {
  icon: IconValue | null;
  title: string;
}

function Editor() {
  const [config, setConfig] = useExtensionStorage<MyConfig>();

  return (
    <CompactView title="Alert Settings">
      <IconPicker
        value={config.icon ?? null}
        onChange={(icon) => setConfig({ ...config, icon })}
        placeholder="Choose alert icon"
        size="md"
      />
      <IconDisplay icon={config.icon ?? null} size={32} />
    </CompactView>
  );
}

Lumio.render(<Editor />, { target: "editor" });
```

## Upload Tab

The upload tab uses `ctx.upload()` internally. Uploaded files are stored in the extension's storage bucket. Limits:

- Max file size: 256 KB
- Accepted formats: PNG, JPG, GIF, SVG, WebP, AVIF
- Quota: 50 files per extension per account

Duplicate uploads are deduplicated by content hash.

---

## SDK / Components / Editor Components

# Editor Components

Editor components build settings UIs for `editor.tsx` and `designer.tsx` surfaces. They serialize via the Worker Reconciler and render as native `@lumio/ui` components on the host -- matching the Lumio design system automatically.

All editor components are imported from `@zaflun/lumio-sdk`.

---

## EditorInput

Text or number input with optional label, placeholder, min/max, and unit suffix.

### Import

```tsx
import { EditorInput } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | Current value |
| `onChange` | `(value: string) => void` | Yes | Change handler |
| `label` | `string` | No | Label text |
| `type` | `"text" \| "number" \| "color"` | No | Input type (default: `"text"`) |
| `placeholder` | `string` | No | Placeholder text |
| `min` | `number` | No | Minimum value (number type) |
| `max` | `number` | No | Maximum value (number type) |
| `step` | `number` | No | Step increment (number type) |
| `unit` | `string` | No | Unit suffix (e.g. `"px"`, `"ms"`) |
| `id` | `string` | No | HTML id attribute |

### Example

```tsx
import { EditorInput, useLumioConfig } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({ ...prev, settings: { ...(prev.settings ?? {}), [key]: value } }));

  return (
    <EditorInput
      label="Font Size"
      type="number"
      value={String(config.settings?.fontSize ?? 16)}
      onChange={(v) => update("fontSize", Number(v))}
      min={8}
      max={200}
      unit="px"
      placeholder="Enter value..."
    />
  );
}
```

---

## EditorTextarea

Multi-line text input with configurable row count.

### Import

```tsx
import { EditorTextarea } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | Current value |
| `onChange` | `(value: string) => void` | Yes | Change handler |
| `label` | `string` | No | Label text |
| `placeholder` | `string` | No | Placeholder text |
| `rows` | `number` | No | Number of visible rows |
| `id` | `string` | No | HTML id attribute |

### Example

```tsx
import { EditorTextarea, useLumioConfig } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({ ...prev, settings: { ...(prev.settings ?? {}), [key]: value } }));

  return (
    <EditorTextarea
      label="Welcome Message"
      value={String(config.settings?.welcome ?? "")}
      onChange={(v) => update("welcome", v)}
      placeholder="Enter a message..."
      rows={4}
    />
  );
}
```

---

## EditorSelect

Dropdown select with predefined options.

### Import

```tsx
import { EditorSelect } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | Currently selected value |
| `onChange` | `(value: string) => void` | Yes | Change handler |
| `options` | `{ value: string; label: string }[]` | Yes | Available options |
| `label` | `string` | No | Label text |
| `id` | `string` | No | HTML id attribute |

### Example

```tsx
import { EditorSelect, useLumioConfig } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({ ...prev, settings: { ...(prev.settings ?? {}), [key]: value } }));

  return (
    <EditorSelect
      label="Position"
      value={String(config.settings?.position ?? "top-right")}
      onChange={(v) => update("position", v)}
      options={[
        { value: "top-left", label: "Top Left" },
        { value: "top-right", label: "Top Right" },
        { value: "bottom-left", label: "Bottom Left" },
        { value: "bottom-right", label: "Bottom Right" },
      ]}
    />
  );
}
```

---

## EditorCheckbox

Toggle checkbox with a label.

### Import

```tsx
import { EditorCheckbox } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `checked` | `boolean` | Yes | Current state |
| `onChange` | `(checked: boolean) => void` | Yes | Change handler |
| `label` | `string` | Yes | Label text |
| `id` | `string` | No | HTML id attribute |

### Example

```tsx
import { EditorCheckbox, useLumioConfig } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({ ...prev, settings: { ...(prev.settings ?? {}), [key]: value } }));

  return (
    <EditorCheckbox
      label="Show timestamps"
      checked={Boolean(config.settings?.showTimestamps ?? true)}
      onChange={(v) => update("showTimestamps", v)}
    />
  );
}
```

---

## EditorSlider

Range slider for selecting a numeric value within bounds.

### Import

```tsx
import { EditorSlider } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `number` | Yes | Current value |
| `onChange` | `(value: number) => void` | Yes | Change handler |
| `label` | `string` | No | Label text |
| `min` | `number` | No | Minimum value |
| `max` | `number` | No | Maximum value |
| `step` | `number` | No | Step increment |
| `unit` | `string` | No | Unit suffix (e.g. `"%"`, `"px"`) |
| `id` | `string` | No | HTML id attribute |

### Example

```tsx
import { EditorSlider, useLumioConfig } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({ ...prev, settings: { ...(prev.settings ?? {}), [key]: value } }));

  return (
    <EditorSlider
      label="Opacity"
      value={Number(config.settings?.opacity ?? 100)}
      onChange={(v) => update("opacity", v)}
      min={0}
      max={100}
      step={5}
      unit="%"
    />
  );
}
```

---

## EditorColorPicker

Color picker with hex input field.

### Import

```tsx
import { EditorColorPicker } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | Current hex color (e.g. `"#6366f1"`) |
| `onChange` | `(value: string) => void` | Yes | Change handler |
| `label` | `string` | No | Label text |
| `id` | `string` | No | HTML id attribute |

### Example

```tsx
import { EditorColorPicker, useLumioConfig } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({ ...prev, settings: { ...(prev.settings ?? {}), [key]: value } }));

  return (
    <EditorColorPicker
      label="Primary Color"
      value={String(config.settings?.primaryColor ?? "#6366f1")}
      onChange={(v) => update("primaryColor", v)}
    />
  );
}
```

---

## EditorFontPicker

Font family picker with optional weight and italic controls. Loads fonts from Google Fonts.

### Import

```tsx
import { EditorFontPicker } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `string` | Yes | Current font family name |
| `onChange` | `(family: string) => void` | Yes | Family change handler |
| `label` | `string` | No | Label text |
| `weight` | `string` | No | Current font weight (e.g. `"400"`, `"700"`) |
| `onWeightChange` | `(weight: string) => void` | No | Weight change handler |
| `italic` | `boolean` | No | Whether italic is active |
| `onItalicChange` | `(italic: boolean) => void` | No | Italic toggle handler |

### Example

```tsx
import { EditorFontPicker, useLumioConfig } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({ ...prev, settings: { ...(prev.settings ?? {}), [key]: value } }));

  return (
    <EditorFontPicker
      label="Display Font"
      value={String(config.settings?.fontFamily ?? "Inter")}
      onChange={(v) => update("fontFamily", v)}
      weight={String(config.settings?.fontWeight ?? "400")}
      onWeightChange={(v) => update("fontWeight", v)}
      italic={Boolean(config.settings?.fontItalic ?? false)}
      onItalicChange={(v) => update("fontItalic", v)}
    />
  );
}
```

---

## EditorFontRow

Compact font styling row combining bold, italic, weight, size, and color controls in a single line.

### Import

```tsx
import { EditorFontRow } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `fontWeight` | `string` | Yes | Current font weight (e.g. `"400"`, `"700"`) |
| `onFontWeightChange` | `(weight: string) => void` | Yes | Weight change handler |
| `italic` | `boolean` | Yes | Whether italic is active |
| `onItalicChange` | `(italic: boolean) => void` | Yes | Italic toggle handler |
| `fontSize` | `number` | Yes | Current font size in pixels |
| `onFontSizeChange` | `(size: number) => void` | Yes | Size change handler |
| `fontColor` | `string` | Yes | Current font color hex |
| `onFontColorChange` | `(color: string) => void` | Yes | Color change handler |

### Example

```tsx
import { EditorFontRow, useLumioConfig } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({ ...prev, settings: { ...(prev.settings ?? {}), [key]: value } }));

  return (
    <EditorFontRow
      fontWeight={String(config.settings?.fontWeight ?? "400")}
      onFontWeightChange={(v) => update("fontWeight", v)}
      italic={Boolean(config.settings?.fontItalic ?? false)}
      onItalicChange={(v) => update("fontItalic", v)}
      fontSize={Number(config.settings?.fontSize ?? 16)}
      onFontSizeChange={(v) => update("fontSize", v)}
      fontColor={String(config.settings?.fontColor ?? "#ffffff")}
      onFontColorChange={(v) => update("fontColor", v)}
    />
  );
}
```

---

## EditorButton

Action button with variant support. Use for triggering actions in the editor panel (reset, test, import).

### Import

```tsx
import { EditorButton } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `label` | `string` | Yes | Button text |
| `onClick` | `() => void` | Yes | Click handler |
| `variant` | `"default" \| "primary" \| "destructive"` | No | Visual variant (default: `"default"`) |
| `fullWidth` | `boolean` | No | Stretch to fill container width |
| `disabled` | `boolean` | No | Prevents clicks and shows disabled state |

### Example

```tsx
import { EditorButton, useMutation } from "@zaflun/lumio-sdk";

function Settings() {
  const { mutate: resetAll } = useMutation("resetDefaults");

  return (
    <>
      <EditorButton
        label="Test Alert"
        variant="primary"
        onClick={() => {/* trigger test */}}
      />
      <EditorButton
        label="Reset to Defaults"
        variant="destructive"
        onClick={() => resetAll()}
      />
    </>
  );
}
```

---

## EditorGroup

Collapsible section for organizing related settings. Renders as an accordion panel.

### Import

```tsx
import { EditorGroup } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `label` | `string` | Yes | Group heading text |
| `collapsed` | `boolean` | No | Initial collapsed state (default: `false`) |
| `children` | `ReactNode` | Yes | Group contents |

### Example

```tsx
import { EditorGroup, EditorSlider, EditorCheckbox, useLumioConfig } from "@zaflun/lumio-sdk";

function Settings() {
  const [config, setConfig] = useLumioConfig();
  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({ ...prev, settings: { ...(prev.settings ?? {}), [key]: value } }));

  return (
    <EditorGroup label="Advanced" collapsed>
      <EditorSlider
        label="Animation Speed"
        value={Number(config.settings?.speed ?? 300)}
        onChange={(v) => update("speed", v)}
        min={100}
        max={2000}
        unit="ms"
      />
      <EditorCheckbox
        label="Enable shadows"
        checked={Boolean(config.settings?.shadows ?? false)}
        onChange={(v) => update("shadows", v)}
      />
    </EditorGroup>
  );
}
```

---

## EditorLabel

Section label or heading text. Use to visually separate groups of controls.

### Import

```tsx
import { EditorLabel } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `text` | `string` | Yes | Label text |
| `htmlFor` | `string` | No | Associated input id |
| `required` | `boolean` | No | Show required indicator |

### Example

```tsx
import { EditorLabel, EditorInput } from "@zaflun/lumio-sdk";

function Settings() {
  return (
    <>
      <EditorLabel text="Display Settings" />
      <EditorInput label="Title" value="" onChange={() => {}} id="title-input" />
    </>
  );
}
```

---

## EditorDivider

Visual horizontal separator. Takes no props.

### Import

```tsx
import { EditorDivider } from "@zaflun/lumio-sdk";
```

### Example

```tsx
import { EditorDivider, EditorInput, EditorColorPicker } from "@zaflun/lumio-sdk";

function Settings() {
  return (
    <>
      <EditorInput label="Title" value="" onChange={() => {}} />
      <EditorDivider />
      <EditorColorPicker label="Background" value="#000000" onChange={() => {}} />
    </>
  );
}
```

---

## EditorInfo

Read-only informational text block. Use for help text, warnings, or descriptions.

### Import

```tsx
import { EditorInfo } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `content` | `string` | Yes | Informational text to display |

### Example

```tsx
import { EditorInfo, EditorInput } from "@zaflun/lumio-sdk";

function Settings() {
  return (
    <>
      <EditorInfo content="Enter the API key from your ESPN developer account. This is required for live score updates." />
      <EditorInput label="API Key" value="" onChange={() => {}} placeholder="Enter API key..." />
    </>
  );
}
```

---

## EditorChannelRow

Compact row for channel configuration: platform dropdown, channel name input, color swatch, and delete button in a single line.

### Import

```tsx
import { EditorChannelRow } from "@zaflun/lumio-sdk";
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `platform` | `string` | Yes | Selected platform (e.g. `"twitch"`) |
| `onPlatformChange` | `(platform: string) => void` | Yes | Platform change handler |
| `channel` | `string` | Yes | Channel name |
| `onChannelChange` | `(channel: string) => void` | Yes | Channel name change handler |
| `color` | `string` | Yes | Background color hex |
| `onColorChange` | `(color: string) => void` | Yes | Color change handler |
| `onRemove` | `() => void` | Yes | Remove button handler |
| `platforms` | `{value: string, label: string}[]?` | No | Custom platform list |

### Example

```tsx
import { EditorChannelRow, EditorButton } from "@zaflun/lumio-sdk";

{channels.map((ch, i) => (
  <EditorChannelRow
    key={i}
    platform={ch.platform}
    onPlatformChange={(v) => updateChannel(i, "platform", v)}
    channel={ch.channel}
    onChannelChange={(v) => updateChannel(i, "channel", v)}
    color={ch.color ?? "#000000"}
    onColorChange={(v) => updateChannel(i, "color", v)}
    onRemove={() => removeChannel(i)}
  />
))}
<EditorButton label="Add Channel" variant="primary" onClick={addChannel} />
```

---

## Complete example

A full editor panel combining multiple editor components:

```tsx
import {
  Lumio,
  EditorGroup,
  EditorInput,
  EditorSelect,
  EditorCheckbox,
  EditorSlider,
  EditorColorPicker,
  EditorFontPicker,
  EditorFontRow,
  EditorDivider,
  EditorInfo,
  EditorButton,
  useLumioConfig,
  useMutation,
} from "@zaflun/lumio-sdk";

function ScoreboardEditor() {
  const [config, setConfig] = useLumioConfig();
  const { mutate: resetScores } = useMutation("resetScores");

  const update = (key: string, value: unknown) =>
    setConfig((prev) => ({
      ...prev,
      settings: { ...(prev.settings ?? {}), [key]: value },
    }));

  const s = config.settings ?? {};

  return (
    <>
      <EditorInfo content="Configure how the scoreboard appears on your overlay." />

      <EditorInput
        label="Home Team"
        value={String(s.homeTeam ?? "")}
        onChange={(v) => update("homeTeam", v)}
        placeholder="Team name..."
      />
      <EditorInput
        label="Away Team"
        value={String(s.awayTeam ?? "")}
        onChange={(v) => update("awayTeam", v)}
        placeholder="Team name..."
      />

      <EditorDivider />

      <EditorSelect
        label="Layout"
        value={String(s.layout ?? "horizontal")}
        onChange={(v) => update("layout", v)}
        options={[
          { value: "horizontal", label: "Horizontal" },
          { value: "vertical", label: "Vertical" },
          { value: "compact", label: "Compact" },
        ]}
      />

      <EditorGroup label="Appearance">
        <EditorColorPicker
          label="Background Color"
          value={String(s.bgColor ?? "#1a1a2e")}
          onChange={(v) => update("bgColor", v)}
        />
        <EditorSlider
          label="Opacity"
          value={Number(s.opacity ?? 100)}
          onChange={(v) => update("opacity", v)}
          min={0}
          max={100}
          unit="%"
        />
        <EditorFontPicker
          label="Font"
          value={String(s.fontFamily ?? "Inter")}
          onChange={(v) => update("fontFamily", v)}
        />
        <EditorFontRow
          fontWeight={String(s.fontWeight ?? "700")}
          onFontWeightChange={(v) => update("fontWeight", v)}
          italic={Boolean(s.fontItalic ?? false)}
          onItalicChange={(v) => update("fontItalic", v)}
          fontSize={Number(s.fontSize ?? 24)}
          onFontSizeChange={(v) => update("fontSize", v)}
          fontColor={String(s.fontColor ?? "#ffffff")}
          onFontColorChange={(v) => update("fontColor", v)}
        />
      </EditorGroup>

      <EditorGroup label="Behavior" collapsed>
        <EditorCheckbox
          label="Auto-hide when inactive"
          checked={Boolean(s.autoHide ?? false)}
          onChange={(v) => update("autoHide", v)}
        />
        <EditorSlider
          label="Hide delay"
          value={Number(s.hideDelay ?? 30)}
          onChange={(v) => update("hideDelay", v)}
          min={5}
          max={120}
          unit="s"
        />
      </EditorGroup>

      <EditorDivider />

      <EditorButton
        label="Reset Scores"
        variant="destructive"
        onClick={() => resetScores()}
        fullWidth
      />
    </>
  );
}

Lumio.render(<ScoreboardEditor />, { target: "editor" });
```

---

## SDK / Rendering

# Rendering

Every extension entry point must call `Lumio.render()` to mount the React component tree. This is the only way to display content in an extension surface.

## Syntax

```tsx
import { Lumio } from "@zaflun/lumio-sdk";

Lumio.render(<MyComponent />, { target: "editor" | "layer" | "interactive" });
```

## Targets

| Target | Surface | Entry file |
|--------|---------|------------|
| `"editor"` | Dashboard sidebar | `src/editor.tsx` |
| `"layer"` | Browser Source | `src/layer.tsx` |
| `"interactive"` | Standalone page | `src/interactive.tsx` |

The `target` value must match the file's surface. Passing the wrong target causes a runtime error.

## 10-second timeout

`Lumio.render()` must be called within **10 seconds** of page load. If the timeout expires, the extension is terminated and the user sees an error message with a "Reload" option.

```tsx
// This will cause termination — render is called too late
setTimeout(() => {
  Lumio.render(<App />, { target: "editor" });
}, 15000); // 15 seconds — too late!
```

The correct pattern is to render immediately with a loading state:

```tsx
// Correct: render immediately, show loading state internally
function App() {
  const { data, isLoading } = useQuery("getData");

  if (isLoading) {
    return (
      <CompactView title="My Extension">
        <Text content="Loading..." variant="muted" />
      </CompactView>
    );
  }

  return <MainUI data={data} />;
}

Lumio.render(<App />, { target: "editor" }); // called immediately
```

## Single call requirement

`Lumio.render()` must be called **exactly once** per entry file. Calling it multiple times is an error:

```tsx
// Wrong: calling render twice
Lumio.render(<App />, { target: "editor" });
Lumio.render(<OtherApp />, { target: "editor" }); // Error!
```

To conditionally render different content, use React's conditional rendering inside a single component:

```tsx
// Correct: one render call, conditional inside
function Root() {
  const [storage] = useExtensionStorage();
  return storage.mode === "advanced" ? <AdvancedUI /> : <SimpleUI />;
}
Lumio.render(<Root />, { target: "editor" });
```

## No direct DOM access

Extensions must use only SDK components. The React reconciler serializes the component tree to a **JSON intermediate representation** (VisionNode tree) that the Lumio host renders as actual DOM elements in the sandboxed iframe.

```tsx
// These have no effect inside the extension sandbox:
document.createElement("div");         // no-op
document.getElementById("root");       // returns null
document.body.appendChild(element);    // no-op
```

Use SDK layout and display components instead:

```tsx
// Use SDK components for all rendering
import { Box, Text, VStack } from "@zaflun/lumio-sdk";

function Layout() {
  return (
    <VStack>
      <Box style={{ padding: 16 }}>
        <Text content="Hello World" variant="heading" />
      </Box>
    </VStack>
  );
}
```

## VisionStyle

All components accept a `style` prop of type `VisionStyle` — a typed subset of CSS properties that the host sanitizes before rendering.

**Allowed properties:**

| Category | Properties |
|----------|-----------|
| **Box model** | `margin`, `padding`, `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight` |
| **Flexbox** | `display`, `flexDirection`, `flexWrap`, `flex`, `alignItems`, `alignSelf`, `justifyContent`, `gap`, `flexShrink`, `flexGrow` |
| **Position** | `position: "relative" \| "absolute"`, `top`, `right`, `bottom`, `left`, `zIndex` |
| **Visual** | `background`, `backgroundColor`, `color`, `opacity`, `border`, `borderRadius`, `boxShadow` |
| **Typography** | `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`, `textAlign`, `textTransform`, `textDecoration` |
| **Transform** | `transform`, `transition`, `animation`, `objectFit` |
| **Misc** | `cursor`, `pointerEvents`, `overflow`, `overflowX`, `overflowY` |

**Blocked properties** (rejected by the host sanitizer):
- `position: "fixed"` or `position: "sticky"`
- CSS `expression()` values
- `javascript:` URLs
- `content` with external resources

## Provider wrapping

`Lumio.render()` automatically wraps the component tree with all necessary context providers:
- Storage context (`useExtensionStorage`)
- Config context (`useLumioConfig`)
- Theme context (`useLumioTheme`)
- Identity context (`useLumioIdentity`)
- Event subscription context (`useLumioEvent`)

You do not need to add any providers manually.

---

## Server Functions / Server Functions Overview

# Server Functions

Server functions are optional server-side logic that runs on the Lumio API. They let extensions persist structured data, query databases, call external APIs, and manage secrets — all in a sandboxed, isolated environment.

## Enabling server functions

Add `"server": true` to `lumio.config.json`:

```json
{
  "server": true
}
```

This enables the `server/` directory and activates the server runtime for your extension.

## Two styles

| Style | Use case | Overhead |
|-------|----------|----------|
| **Declarative** | Simple CRUD on tables (`queryRows`, `insertRow`, `patchRow`, `deleteRow`) | Minimal — transpiles to parameterized SQL, no JS runtime |
| **Handler-based** | Complex logic, external APIs, conditional writes (`query()`, `mutation()`, `action()`) | Low — runs in a V8 isolate with memory and CPU limits |

## Execution flow

```
Extension Client (browser)
  -> useMutation("addRule") / useQuery("getRules")
  -> postMessage to Lumio host
  -> Lumio API: POST /v1/extension-functions/{install_id}/{functionName}
  -> Auth check + rate limit check
  -> Declarative: parameterized SQL -> PostgreSQL (ext_{extension_id}.*)
  -> Handler: V8 isolate -> ctx.db / ctx.fetch / ctx.secrets
  -> Response serialized to JSON
  -> postMessage back to extension
```

## Rate limits

| Function type | Limit | Applies to |
|---------------|-------|-----------|
| `queryRows` | 100 calls/minute | Per installation |
| `insertRow` / `patchRow` / `deleteRow` | 50 calls/minute | Per installation |
| `query()` | 100 calls/minute | Per installation |
| `mutation()` | 50 calls/minute | Per installation |
| `action()` | 20 calls/minute | Per installation |

## Database isolation

Each extension gets its own isolated PostgreSQL schema: `ext_{extension_id}`. Tables defined in `server/schema.ts` live in this schema:

```
ext_88b2478a_39c7_468e_bebd_14e52fd97ac0.rules
ext_88b2478a_39c7_468e_bebd_14e52fd97ac0.votes
```

No extension can read or write another extension's tables. The Lumio API enforces this at the query level.

## File structure

```
server/
├── schema.ts       <- Table definitions (defineSchema + defineTable)
└── functions.ts    <- Function exports (queryRows, action, etc.)
```

Both files are optional. An extension can have `server: true` but only use schema for `useExtensionStorage()` type safety, without defining custom functions.

## When to use server functions

| Scenario | Recommendation |
|----------|---------------|
| Simple toggle / text setting | `useExtensionStorage()` — no server needed |
| List of items (rules, songs, votes) | Declarative server functions + `defineTable` |
| Aggregations (count, sum, averages) | Handler-based `query()` |
| External API calls (sports scores, weather) | Handler-based `action()` |
| User-specific data (per-viewer state) | Handler-based with `ctx.auth.userId` |
| Secrets (API keys) | Handler-based `action()` with `ctx.secrets` |

---

## Server Functions / Schema

# Schema

Define your extension's database tables in `server/schema.ts` using `defineSchema` and `defineTable` from `@zaflun/lumio-sdk/server`.

## Basic example

```typescript
// server/schema.ts
import { defineSchema, defineTable, v } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  rules: defineTable({
    text: v.string(),
    revealed: v.boolean(),
    score: v.number().optional(),
    tags: v.array(v.string()).optional(),
  }).storage("instance"),

  votes: defineTable({
    choice: v.string(),
    userId: v.string(),
    weight: v.number().optional(),
  }).storage("account"),
});
```

## `defineSchema`

Wraps a map of table definitions. Each key is the table name used in functions (`queryRows("rules")`, etc.).

```typescript
import { defineSchema, defineTable, v } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  tableName: defineTable({ /* field validators */ }).storage("scope"),
  // ...
});
```

## `defineTable`

Defines the columns of a table. Accepts a record of field names to validators.

```typescript
defineTable({
  fieldName: validator,
  // ...
})
```

Every table automatically gets these system columns — you do not define them:
- `id` — `text` primary key (UUID, auto-generated)
- `created_at` — `timestamptz` (auto-set on insert)
- `updated_at` — `timestamptz` (auto-updated on patch)

## Validators

| Validator | Type | Example |
|-----------|------|---------|
| `v.string()` | `TEXT` | `v.string()` |
| `v.number()` | `DOUBLE PRECISION` | `v.number()` |
| `v.boolean()` | `BOOLEAN` | `v.boolean()` |
| `v.array(v.string())` | `TEXT[]` | `v.array(v.string())` |
| `v.array(v.number())` | `DOUBLE PRECISION[]` | `v.array(v.number())` |
| `v.object({ ... })` | `JSONB` | `v.object({ x: v.number(), y: v.number() })` |

### `.optional()` modifier

Appending `.optional()` makes the field nullable in SQL and optional in TypeScript:

```typescript
defineTable({
  text: v.string(),           // required, NOT NULL
  score: v.number().optional(), // nullable, REAL | null
  notes: v.string().optional(), // nullable, TEXT | null
})
```

## Storage scopes

Chain `.storage(scope)` to control which installation instances share the same table data:

| Scope | Description | Use case |
|-------|-------------|----------|
| `"instance"` | One set of rows per overlay install | Rules for a specific overlay |
| `"overlay"` | Shared across all installs on the same overlay | Per-overlay leaderboard |
| `"account"` | Shared across all overlays in an account | Account-wide vote history |
| `"global"` | Shared across all installs of this extension everywhere | Global leaderboard |

```typescript
export default defineSchema({
  rules: defineTable({
    text: v.string(),
    revealed: v.boolean(),
  }).storage("instance"),   // each overlay install has its own rules

  globalLeaderboard: defineTable({
    userName: v.string(),
    score: v.number(),
  }).storage("global"),     // all installs share this leaderboard
});
```

## Migrations

Schema changes are **additive only** — you can add new tables and add nullable columns to existing tables. Removing tables or columns, or changing column types, requires a manual migration step via the extension dashboard.

> **Never rename a field in `defineTable` without a migration plan. The old column name remains in PostgreSQL; the new name creates a new column.:**
> 
## Full example

```typescript
// server/schema.ts
import { defineSchema, defineTable, v } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  // Challenge rules — one set per overlay install
  rules: defineTable({
    text: v.string(),
    revealed: v.boolean(),
    category: v.string().optional(),
  }).storage("instance"),

  // Votes — shared across the account
  votes: defineTable({
    ruleId: v.string(),
    userId: v.string(),
    choice: v.string(),
  }).storage("account"),

  // Config snapshots — per instance
  snapshots: defineTable({
    label: v.string(),
    data: v.object({
      homeTeam: v.string(),
      awayTeam: v.string(),
      homeScore: v.number(),
      awayScore: v.number(),
    }),
  }).storage("instance"),
});
```

---

## Server Functions / Declarative Functions

# Declarative Functions

Declarative server functions are defined with `queryRows`, `insertRow`, `patchRow`, and `deleteRow`. They translate directly to parameterized SQL at compile time — no V8 isolate, minimal overhead.

## When to use declarative

Use declarative functions for standard CRUD operations on tables defined in your schema. For complex business logic, aggregations, or external API calls, use [handler-based functions](/server-functions/handler-based) instead.

## Basic example

```typescript
// server/functions.ts
import { queryRows, insertRow, patchRow, deleteRow, arg } from "@zaflun/lumio-sdk/server";

// List all rules
export const getRules = queryRows("rules");

// Add a new rule (editor only — streamers only, not viewers)
export const addRule = insertRow("rules", {
  text: arg("text"),
  revealed: false,
}, { editorOnly: true });

// Reveal a rule
export const revealRule = patchRow("rules", arg("id"), {
  revealed: true,
}, { editorOnly: true });

// Delete a rule
export const deleteRule = deleteRow("rules", arg("id"), { editorOnly: true });
```

## `queryRows`

Returns all rows from a table, ordered by `created_at ASC`.

```typescript
queryRows(tableName: string, options?: QueryOptions): ServerQuery
```

### Options

| Option | Type | Description |
|--------|------|-------------|
| `filter` | `Filter` | Condition to filter rows |
| `orderBy` | `string` | Column name to sort by (default: `"created_at"`) |
| `orderDir` | `"asc" \| "desc"` | Sort direction (default: `"asc"`) |
| `limit` | `number \| arg` | Maximum rows to return |
| `offset` | `number \| arg` | Rows to skip (for pagination) |

```typescript
// List only revealed rules, newest first
export const getRevealedRules = queryRows("rules", {
  filter: filter("revealed", "=", true),
  orderBy: "created_at",
  orderDir: "desc",
});

// Paginated rules
export const getRulesPaged = queryRows("rules", {
  limit: arg("limit"),
  offset: arg("offset"),
});
```

## `insertRow`

Inserts a new row into a table. Returns the inserted row including its generated `id` and `created_at`.

```typescript
insertRow(tableName: string, data: DataObject, options?: MutationOptions): ServerMutation
```

### DataObject

A record of field names to values or `arg()` references:

```typescript
export const addRule = insertRow("rules", {
  text: arg("text"),          // value comes from caller: addRule({ text: "..." })
  revealed: false,            // static value
  category: arg("category"),  // optional dynamic value
});
```

## `patchRow`

Updates specific fields of an existing row. The first `arg()` or value after `tableName` is the row `id`.

```typescript
patchRow(tableName: string, id: string | arg, data: DataObject, options?: MutationOptions): ServerMutation
```

```typescript
// Reveal a specific rule
export const revealRule = patchRow("rules", arg("id"), {
  revealed: true,
});

// Update multiple fields
export const updateRule = patchRow("rules", arg("id"), {
  text: arg("text"),
  category: arg("category"),
});
```

## `deleteRow`

Deletes a row by its `id`.

```typescript
deleteRow(tableName: string, id: string | arg, options?: MutationOptions): ServerMutation
```

```typescript
export const deleteRule = deleteRow("rules", arg("id"), { editorOnly: true });
```

## `arg()`

The `arg()` helper marks a field as a dynamic parameter supplied by the caller at runtime:

```typescript
import { insertRow, arg } from "@zaflun/lumio-sdk/server";

export const addVote = insertRow("votes", {
  choice: arg("choice"),    // caller provides: castVote({ choice: "yes" })
  userId: arg("userId"),    // caller provides: castVote({ userId: "..." })
  weight: 1,                // static value
});
```

`arg("name")` is substituted with a SQL `$n` parameter placeholder — preventing SQL injection.

## `filter()`

Build filter conditions for `queryRows`:

```typescript
import { filter, arg } from "@zaflun/lumio-sdk/server";

// Static filter
export const getRevealedRules = queryRows("rules", {
  filter: filter("revealed", "=", true),
});

// Dynamic filter (value from caller)
export const getRulesByCategory = queryRows("rules", {
  filter: filter("category", "=", arg("category")),
});
```

### Supported operators

| Operator | SQL equivalent |
|----------|---------------|
| `"="` | `=` |
| `"!="` | `<>` |
| `">"` | `>` |
| `">="` | `>=` |
| `"<"` | `<` |
| `"<="` | `<=` |
| `"like"` | `LIKE` |
| `"in"` | `= ANY(...)` |

## `editorOnly` option

Mutations with `editorOnly: true` can only be called from the editor surface. Calls from the layer or interactive surface are rejected with a permission error:

```typescript
export const deleteRule = deleteRow("rules", arg("id"), {
  editorOnly: true, // only the streamer/editor can delete
});
```

Use this for admin operations that viewers on the interactive page should not be able to perform.

---

## Server Functions / Handler-based Functions

# Handler-based Functions

Handler-based server functions use `query()`, `mutation()`, and `action()`. They run JavaScript inside a V8 isolate with access to the database, secrets, and (for actions) external HTTP APIs.

## When to use handler-based

| Use case | Function type |
|----------|--------------|
| Complex query with aggregation | `query()` |
| Conditional logic before write | `mutation()` |
| External HTTP API calls | `action()` |
| Reading secrets | `action()` |

## `query()`

A read-only function. Has access to `ctx.db` but not `ctx.fetch` or `ctx.secrets`.

```typescript
// server/functions.ts
import { query, v } from "@zaflun/lumio-sdk/server";

export const getLeaderboard = query({
  args: { limit: v.number() },
  handler: async (ctx, args) => {
    const rows = await ctx.db.query("votes", {
      orderBy: "score",
      orderDir: "desc",
      limit: args.limit,
    });
    return rows;
  },
});
```

## `mutation()`

A read-write function. Has access to `ctx.db` and `ctx.auth`. Can read and write rows conditionally.

```typescript
import { mutation, v } from "@zaflun/lumio-sdk/server";

export const castVote = mutation({
  args: { ruleId: v.string(), choice: v.string() },
  handler: async (ctx, args) => {
    const userId = ctx.auth.userId;
    if (!userId) throw new Error("Must be authenticated to vote");

    // Check for existing vote
    const existing = await ctx.db.get("votes", {
      filter: { userId, ruleId: args.ruleId },
    });

    if (existing) {
      // Update existing vote
      await ctx.db.patch("votes", existing.id, { choice: args.choice });
    } else {
      // Insert new vote
      await ctx.db.insert("votes", {
        userId,
        ruleId: args.ruleId,
        choice: args.choice,
      });
    }

    return { success: true };
  },
});
```

## `action()`

A full-capability function. Has access to `ctx.db`, `ctx.auth`, `ctx.fetch`, and `ctx.secrets`. Suitable for external API calls.

```typescript
import { action, v } from "@zaflun/lumio-sdk/server";

export const getScoreboard = action({
  args: { sport: v.string(), league: v.string() },
  handler: async (ctx, args) => {
    const apiKey = ctx.secrets.get("ESPN_API_KEY");

    const res = await ctx.fetch(
      `https://site.api.espn.com/apis/site/v2/sports/${args.sport}/${args.league}/scoreboard`,
      {
        headers: { "Authorization": `Bearer ${apiKey}` },
      }
    );

    if (!res.ok) {
      throw new Error(`ESPN API error: ${res.status}`);
    }

    const data = await res.json();
    return data.events.slice(0, 5);
  },
});
```

## The `ctx` object

All handler-based functions receive a `ctx` (context) object as the first argument:

### `ctx.db`

Database access for the extension's isolated schema:

```typescript
// Get a single row by ID
const row = await ctx.db.get("rules", "some-uuid");

// Query rows with filter
const rows = await ctx.db.query("rules", {
  filter: { revealed: true },
  orderBy: "created_at",
  limit: 10,
});

// Insert a row
const newRow = await ctx.db.insert("rules", {
  text: "Complete the game without dying",
  revealed: false,
});

// Update fields
await ctx.db.patch("rules", row.id, { revealed: true });

// Delete a row
await ctx.db.delete("rules", row.id);
```

### `ctx.auth`

Identity information for the caller:

| Property | Type | Description |
|----------|------|-------------|
| `userId` | `string \| null` | Lumio user ID, or `null` for unauthenticated |
| `accountId` | `string` | Account that owns this installation |
| `role` | `"owner" \| "editor" \| "viewer" \| "anonymous"` | Caller's role |
| `surface` | `"editor" \| "layer" \| "interactive"` | Which surface called this function |

### `ctx.fetch`

An egress-restricted version of `fetch()`. Only URLs matching the extension's egress allowlist are permitted:

```typescript
// Works if site.api.espn.com is in the allowlist
const res = await ctx.fetch("https://site.api.espn.com/...");

// Rejected: not in allowlist
const res = await ctx.fetch("https://malicious.example.com/..."); // throws
```

See [External APIs](/server-functions/external-apis) for allowlist configuration.

### `ctx.secrets`

Access secrets stored in the extension dashboard:

```typescript
const apiKey = ctx.secrets.get("MY_API_KEY"); // returns string | null
```

See [Secrets](/server-functions/secrets) for management instructions.

### `ctx.cache`

Scoped Redis key-value cache available to all server functions. Faster than `ctx.db` for temporary data.

```typescript
await ctx.cache.set("counter", 42, 3600);
const val = await ctx.cache.get("counter");
await ctx.cache.increment("counter", 1);
await ctx.cache.delete("counter");
```

Keys are scoped per install (`ext-cache:{install_id}:*`). Max TTL 24h, default 1h. See [Cache & Background Jobs](/guides/cache-and-defer).

### `ctx.defer`

Queue a function to run after the handler returns — useful for background DB writes after a fast cache read.

```typescript
ctx.defer(async () => {
  await ctx.db.patch("stats", id, { count: newCount });
});
```

Max 5 deferred calls per handler invocation. Each has a 10s timeout. See [Cache & Background Jobs](/guides/cache-and-defer).

## Sandbox limits

Handler-based functions run in a V8 isolate with these constraints:

| Limit | Value |
|-------|-------|
| Memory | 128 MB per invocation |
| CPU timeout | 5 seconds |
| Response size | 4 MB |
| `ctx.fetch` calls per invocation | 10 |
| Concurrent invocations per installation | 5 |

Exceeding any limit terminates the invocation and returns an error to the client.

## Validators

Use `v` (from `@zaflun/lumio-sdk/server`) to type-check function arguments:

```typescript
import { action, v } from "@zaflun/lumio-sdk/server";

export const example = action({
  args: {
    name: v.string(),
    count: v.number(),
    enabled: v.boolean(),
    tags: v.array(v.string()),
    config: v.object({ x: v.number(), y: v.number() }),
    optionalNote: v.string().optional(),
  },
  handler: async (ctx, args) => {
    // args is fully typed: { name: string, count: number, enabled: boolean, ... }
  },
});
```

Arguments that do not match the declared validators are rejected before the handler runs.

## Bot module handlers

Bot module extensions use a different set of handler wrappers optimized for chat interaction. These wrappers set a `__type` discriminant on the exported function, which the CLI reads during bundling to register the handler type.

### `command()`

Handles chat commands triggered by a prefix (e.g., `!points`). Runs on the sync execution path with a 500ms deadline.

```typescript
import { command } from "@zaflun/lumio-sdk/server";

export const points = command("points", async (ctx, args) => {
  const balance = await ctx.db.get("user_points", ctx.user.id);
  return { reply: `${ctx.user.name} has ${balance?.balance ?? 0} points` };
});
```

**Parameters:**
- `name` — command name (matches `triggers.commands[].name` in the manifest)
- `handler(ctx, args)` — async function receiving `BotModuleContext` and a `string[]` of parsed arguments

**Returns:** `{ reply?: string, actions?: ActionRequest[] }` or `null`

### `keyword()`

Fires when a substring match is found in a chat message. Runs on the async execution path.

```typescript
import { keyword } from "@zaflun/lumio-sdk/server";

export const hypeDetector = keyword("gg", async (ctx, message) => {
  await ctx.cache.increment("hype_count", 1);
  return null;
});
```

**Parameters:**
- `word` — keyword string (matches `triggers.keywords[]` in the manifest)
- `handler(ctx, message)` — async function receiving context and the chat message object

### `pattern()`

Fires when a regex pattern matches in a chat message. The pattern is matched by the Rust bot — JavaScript `RegExp` is never used for trigger matching.

```typescript
import { pattern } from "@zaflun/lumio-sdk/server";

export const clipLogger = pattern(
  "https?://clips\\.twitch\\.tv/\\S+",
  async (ctx, message, matched) => {
    return { reply: `Clip from ${ctx.user.name}: ${matched}` };
  }
);
```

**Parameters:**
- `regex` — regex pattern string (matches `triggers.patterns[]` in the manifest)
- `handler(ctx, message, matched)` — async function receiving context, message, and the matched substring

### `event()`

Fires when a platform event occurs (subscriptions, raids, donations, etc.).

```typescript
import { event } from "@zaflun/lumio-sdk/server";

export const welcomeSub = event("twitch:subscribe", async (ctx, evt) => {
  return { reply: `Welcome ${evt.user_name}! Thanks for subscribing!` };
});
```

**Parameters:**
- `eventType` — event type string (matches `triggers.events[]` in the manifest)
- `handler(ctx, evt)` — async function receiving context and the event payload

### `timer()`

Fires at a configured interval. Timer handlers have no chat sender — `ctx.user` is `null`.

```typescript
import { timer } from "@zaflun/lumio-sdk/server";

export const periodicReminder = timer("reminder", async (ctx) => {
  return { reply: "Remember to follow the channel!" };
});
```

**Parameters:**
- `name` — timer name (matches `triggers.timers[].handler` in the manifest)
- `handler(ctx)` — async function receiving context only

### `moderate()`

Runs on every chat message that passes built-in module checks. Uses the sync execution path with a 500ms deadline. Requires `chat:ban` or `chat:delete` permission.

```typescript
import { moderate } from "@zaflun/lumio-sdk/server";

export const linkFilter = moderate(async (ctx, message) => {
  if (message.text.includes("banned-site.com")) {
    return { block: true, action: "timeout", duration: 60, reason: "Banned link" };
  }
  return { block: false };
});
```

**Parameters:**
- `handler(ctx, message)` — async function receiving context and the chat message

**Returns:** `{ block: boolean, action?: "delete" | "timeout" | "ban", duration?: number, reason?: string }`

See [Bot Module Context](/sdk/hooks/bot-module-context) for the full `ctx` API reference.

---

## Server Functions / Storage Scoping

# Storage Scoping

Each table in your extension's schema can be scoped to control which installations share the same data. The scope is declared with `.storage(scope)` on `defineTable`.

## Scopes

| Scope | Rows shared by | Use case |
|-------|---------------|----------|
| `"instance"` | One specific overlay install | Per-install rules, settings, state |
| `"overlay"` | All installs on the same overlay | Shared overlay leaderboard |
| `"account"` | All installs across all overlays in one account | Account-wide vote history |
| `"global"` | All installs of this extension across all accounts | Global community leaderboard |

## Example

```typescript
// server/schema.ts
import { defineSchema, defineTable, v } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  // One set of rules per overlay install
  rules: defineTable({
    text: v.string(),
    revealed: v.boolean(),
  }).storage("instance"),

  // Votes shared across all overlays in the account
  votes: defineTable({
    choice: v.string(),
    userId: v.string(),
  }).storage("account"),

  // Global leaderboard shared across ALL streamers using this extension
  globalLeaderboard: defineTable({
    accountId: v.string(),
    score: v.number(),
    userName: v.string(),
  }).storage("global"),
});
```

## How scoping works

The scope is implemented via a `scope_key` column added automatically to each table:

| Scope | `scope_key` value |
|-------|------------------|
| `"instance"` | `install_id` (UUID of this specific install) |
| `"overlay"` | `overlay_id` (UUID of the overlay) |
| `"account"` | `account_id` (UUID of the account) |
| `"global"` | `extension_id` (UUID of the extension itself) |

All declarative functions (`queryRows`, `insertRow`, etc.) and `ctx.db` operations automatically filter by the correct `scope_key` based on the calling installation's context. You never need to filter by scope manually.

## Choosing the right scope

### `"instance"` (most common)

Use when each overlay install should have completely independent data:

```typescript
// Each overlay the streamer creates has its own rules list
rules: defineTable({ text: v.string() }).storage("instance")
```

### `"overlay"`

Use when multiple extensions installed on the same overlay should share data (rare):

```typescript
// All extensions on "Gaming Overlay 1" share this chat log
chatLog: defineTable({ message: v.string() }).storage("overlay")
```

### `"account"`

Use when data should persist across all overlays a streamer creates:

```typescript
// Song requests appear on all overlays for this streamer
songRequests: defineTable({ title: v.string(), artist: v.string() }).storage("account")
```

### `"global"`

Use for community features across all streamers:

```typescript
// Global trivia high scores across all Lumio streamers
highScores: defineTable({
  accountId: v.string(),
  userName: v.string(),
  score: v.number(),
}).storage("global")
```

> **`"global"` scope means **any installation can read and write this data**. Use it only for truly public, community data. Never store sensitive or per-streamer data in global scope.:**
> 
## Mixing scopes in one schema

You can mix scopes freely within one schema:

```typescript
export default defineSchema({
  rules: defineTable({ text: v.string() }).storage("instance"),    // per install
  votes: defineTable({ choice: v.string() }).storage("account"),   // per account
  topPlays: defineTable({ score: v.number() }).storage("global"),  // global
});
```

---

## Server Functions / Auth and Scopes

# Auth and Scopes

Server functions can inspect the identity of the caller and restrict access based on surface, role, or authentication status.

## `ctx.auth`

Available in all handler-based functions (`query()`, `mutation()`, `action()`):

```typescript
export const myMutation = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    const { userId, accountId, role, surface } = ctx.auth;

    if (!userId) {
      throw new Error("Authentication required");
    }

    if (role !== "owner" && role !== "editor") {
      throw new Error("Only editors can perform this action");
    }

    // ... proceed
  },
});
```

### `ctx.auth` properties

| Property | Type | Description |
|----------|------|-------------|
| `userId` | `string \| null` | Lumio user ID, or `null` for unauthenticated visitors |
| `accountId` | `string` | The Lumio account that owns this installation |
| `role` | `"owner" \| "editor" \| "viewer" \| "anonymous"` | Caller's role in the account |
| `surface` | `"editor" \| "layer" \| "interactive"` | Which surface made this request |
| `platformUserId` | `string \| null` | Platform user ID if viewer is connected |
| `platformUserName` | `string \| null` | Platform username if viewer is connected |

## `editorOnly` for declarative functions

For declarative functions, use the `editorOnly` option instead of `ctx.auth`:

```typescript
// Only the editor surface can call this
export const deleteRule = deleteRow("rules", arg("id"), { editorOnly: true });

// Any surface can call this
export const getRules = queryRows("rules");
```

`editorOnly: true` is equivalent to checking `ctx.auth.surface === "editor"` in a handler function. Use it when:
- The operation is destructive (delete, reset)
- The operation changes configuration (only the streamer/editor should control this)
- You want to prevent viewers from triggering writes through the interactive surface

## Surface-based restrictions

In handler functions, use `ctx.auth.surface` to apply different logic per surface:

```typescript
export const addItem = mutation({
  args: { text: v.string() },
  handler: async (ctx, args) => {
    if (ctx.auth.surface === "layer") {
      throw new Error("Cannot write from the layer surface");
    }

    if (ctx.auth.surface === "interactive" && !ctx.auth.userId) {
      throw new Error("Must be logged in to submit from the interactive page");
    }

    await ctx.db.insert("items", {
      text: args.text,
      userId: ctx.auth.userId,
      submittedFrom: ctx.auth.surface,
    });
  },
});
```

## Anonymous access on the interactive surface

The interactive surface allows unauthenticated visitors (they have a short-lived token but no Lumio account). Use `ctx.auth.userId` to differentiate:

```typescript
export const castVote = mutation({
  args: { choice: v.string() },
  handler: async (ctx, args) => {
    // Allow anonymous votes (token is sufficient for interactive surface)
    // Use platformUserId as a fallback identifier
    const voterId = ctx.auth.userId ?? ctx.auth.platformUserId ?? "anonymous";

    await ctx.db.insert("votes", {
      choice: args.choice,
      voterId,
    });
  },
});
```

## Role-based access

Use `ctx.auth.role` to restrict operations to specific account roles:

```typescript
export const resetAll = mutation({
  args: {},
  handler: async (ctx) => {
    if (ctx.auth.role !== "owner") {
      throw new Error("Only the account owner can reset all data");
    }

    // Perform destructive reset...
  },
});
```

## Summary

| Restriction type | Mechanism |
|-----------------|-----------|
| Editor surface only | `{ editorOnly: true }` option on declarative functions |
| Surface check in handler | `ctx.auth.surface === "editor"` |
| Authentication required | `if (!ctx.auth.userId) throw ...` |
| Role check | `if (ctx.auth.role !== "owner") throw ...` |
| Platform identity | `ctx.auth.platformUserId` / `ctx.auth.platformUserName` |

---

## Server Functions / External APIs

# External APIs

Handler-based `action()` functions can call external HTTP APIs using `ctx.fetch()`. All outbound requests are restricted to an explicit allowlist declared in `lumio.config.json`.

## Declaring the egress allowlist

Add an `egress` section to `lumio.config.json`:

```json
{
  "egress": {
    "allowHosts": [
      "site.api.espn.com",
      "api.openweathermap.org",
      "*.scdn.co"
    ]
  }
}
```

Only listed hosts are reachable from `ctx.fetch()`. Requests to unlisted hosts are rejected before the network layer.

## Using `ctx.fetch`

`ctx.fetch` has the same interface as the standard `fetch()` API:

```typescript
import { action, v } from "@zaflun/lumio-sdk/server";

export const getWeather = action({
  args: { city: v.string() },
  handler: async (ctx, args) => {
    const apiKey = ctx.secrets.get("OPENWEATHER_API_KEY");

    const res = await ctx.fetch(
      `https://api.openweathermap.org/data/2.5/weather?q=${encodeURIComponent(args.city)}&appid=${apiKey}&units=metric`
    );

    if (!res.ok) {
      throw new Error(`Weather API error: ${res.status} ${res.statusText}`);
    }

    const data = await res.json();
    return {
      temperature: data.main.temp,
      description: data.weather[0].description,
      city: data.name,
    };
  },
});
```

## Wildcard support

Wildcards (`*`) match any subdomain at that level only:

| Pattern | Matches | Does not match |
|---------|---------|---------------|
| `*.espn.com` | `api.espn.com`, `site.espn.com` | `espn.com`, `a.b.espn.com` |
| `*.scdn.co` | `i.scdn.co`, `p.scdn.co` | `scdn.co` |
| `api.example.com` | `api.example.com` exactly | `sub.api.example.com` |

## Security constraints

| Rule | Description |
|------|-------------|
| **HTTPS only** | All `ctx.fetch()` requests must use `https://` — HTTP is blocked |
| **No private IPs** | Requests to RFC 1918 ranges (`10.x`, `172.16.x`, `192.168.x`) and localhost are blocked |
| **Allowlist required** | A `ctx.fetch()` to any host not in `allowHosts` throws immediately |
| **10 requests/invocation** | Maximum 10 `ctx.fetch()` calls per action invocation |
| **30-second timeout** | Each request times out after 30 seconds |

## Setting ports

By default, only port 443 (HTTPS) is allowed. To use a non-standard port, declare it explicitly:

```json
{
  "egress": {
    "allowHosts": ["my-server.example.com"],
    "allowPorts": [8443, 9443]
  }
}
```

## Review process

The egress allowlist is reviewed during the admin approval process. Reviewers check:
- Are the listed hosts appropriate for the extension's stated purpose?
- Are wildcards too broad?
- Are the hosts known, reputable services?

Requests to social engineering domains, telemetry/tracking hosts, or hosts unrelated to the extension's function will result in rejection.

## Example: Sports scoreboard

```json
{
  "extensionId": "...",
  "name": "Sports Scoreboard",
  "server": true,
  "egress": {
    "allowHosts": [
      "site.api.espn.com",
      "cdn.espn.com"
    ]
  }
}
```

```typescript
// server/functions.ts
export const getScoreboard = action({
  args: { sport: v.string(), league: v.string() },
  handler: async (ctx, args) => {
    const res = await ctx.fetch(
      `https://site.api.espn.com/apis/site/v2/sports/${args.sport}/${args.league}/scoreboard`
    );
    const data = await res.json();
    return data.events ?? [];
  },
});
```

---

## Server Functions / Secrets

# Secrets

Secrets let you store sensitive values — API keys, tokens, passwords — that your extension needs to call external services. They are stored encrypted in the Lumio database and injected into `ctx.secrets` at runtime.

## Adding a secret

Secrets are managed in the extension dashboard under **Settings → Secrets**, or via the CLI:

```bash
lumio env set MY_API_KEY "sk-abc123..."
```

Secrets are stored with **AES-256-GCM** encryption. Only your extension's server functions can read them — Lumio staff cannot view the plaintext values.

## Using secrets in action functions

```typescript
// server/functions.ts
import { action, v } from "@zaflun/lumio-sdk/server";

export const callExternalApi = action({
  args: { query: v.string() },
  handler: async (ctx, args) => {
    // Read the secret by name
    const apiKey = ctx.secrets.get("MY_API_KEY");

    if (!apiKey) {
      throw new Error("MY_API_KEY is not configured. Add it in the extension dashboard.");
    }

    const res = await ctx.fetch("https://api.example.com/search", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ query: args.query }),
    });

    return res.json();
  },
});
```

## `ctx.secrets.get(name)`

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | `string` | The secret name as set in the dashboard or CLI |
| Returns | `string \| null` | The secret value, or `null` if not set |

Always handle the `null` case — if a secret is not configured, throw a helpful error rather than failing silently.

## Managing secrets via CLI

```bash
# Set a secret
lumio env set API_KEY "your-api-key-here"

# List secret names (values are never shown)
lumio env list

# Delete a secret
lumio env delete API_KEY
```

## Managing secrets via dashboard

Navigate to **Dashboard → Extensions → {your extension} → Settings → Secrets**:

1. Click **Add secret**
2. Enter the secret name (e.g. `ESPN_API_KEY`)
3. Enter the secret value
4. Click **Save**

The secret is available to your extension immediately — no redeploy required.

## Security model

| Property | Value |
|----------|-------|
| Encryption | AES-256-GCM with per-secret keys |
| Storage | PostgreSQL `ext_secrets` table, values never in plaintext |
| Access | Only `ctx.secrets` in action handlers — never in client code |
| Scoping | Secrets are per-extension per-environment (staging vs production) |
| Audit | Every `ctx.secrets.get()` call is logged in the extension audit log |

## Never expose secrets client-side

Secrets are **only available in server functions**. Never pass a secret back to the client in a function's return value:

```typescript
// WRONG: never return secret values
export const badAction = action({
  args: {},
  handler: async (ctx) => {
    const key = ctx.secrets.get("API_KEY");
    return { apiKey: key }; // exposes the key to the browser!
  },
});

// Correct: use the secret server-side only
export const goodAction = action({
  args: { query: v.string() },
  handler: async (ctx, args) => {
    const key = ctx.secrets.get("API_KEY");
    const res = await ctx.fetch(`https://api.example.com/q=${args.query}`, {
      headers: { "Authorization": `Bearer ${key}` },
    });
    return res.json(); // return API result, not the key
  },
});
```

---

## Server Functions / Real-time Updates

# Real-time Updates

Extensions receive real-time updates via WebSocket when storage or server-side state changes.

## Automatic storage sync

`useExtensionStorage()` is automatically synced via the `ext-storage:{install_id}` WebSocket channel. When any surface calls `setStorage()`, all other surfaces re-render within milliseconds — no polling, no manual refresh.

```
Editor: setStorage({ score: 3 })
  -> Lumio API updates storage
  -> Redis PUBLISH to ext-storage:{install_id}
  -> WebSocket server broadcasts update
  -> Layer: useExtensionStorage() re-renders with score = 3
  -> Interactive: useExtensionStorage() re-renders with score = 3
```

This is completely automatic. You do not need to configure any WebSocket connections.

## Manual refetch after mutations

Server function results are **not** automatically refreshed when storage changes. After calling a mutation, call `refetch()` on any affected queries:

```tsx
import { useQuery, useMutation, Button } from "@zaflun/lumio-sdk";

function RuleManager() {
  const { data: rules, refetch } = useQuery("getRules");
  const { mutate: addRule } = useMutation("addRule");

  const handleAdd = async () => {
    await addRule({ text: "New rule" });
    refetch(); // manually trigger re-query
  };

  return <Button label="Add rule" onClick={handleAdd} />;
}
```

## Real-time events

Use `useLumioEvent()` to subscribe to real-time platform events (Twitch followers, YouTube superchats, etc.). Events are pushed via the Lumio event WebSocket channel and do not require any setup:

```tsx
import { useLumioEvent } from "@zaflun/lumio-sdk";

function LiveCounter() {
  const event = useLumioEvent("twitch:follower");
  const [count, setCount] = useState(0);

  useEffect(() => {
    if (event) {
      setCount((prev) => prev + 1);
    }
  }, [event]);

  return <Text content={`${count} new followers`} />;
}
```

## WebSocket channel reference

| Channel | Triggered by | Received by |
|---------|-------------|-------------|
| `ext-storage:{install_id}` | `setStorage()` on any surface | All surfaces for this install |
| `events:{account_id}` | Platform events (Twitch, YouTube, etc.) | All extensions on this account |

## Connection handling

The Lumio SDK automatically manages WebSocket reconnection. If the connection drops:
- The SDK retries with exponential backoff
- `useExtensionStorage()` shows the last known value during reconnection
- `useLumioEvent()` will miss events that occurred during the disconnect period (events are not replayed)

## Polling as a fallback

For server function data that needs to stay fresh (e.g., a leaderboard that other users update), implement polling with `useEffect`:

```tsx
import { useQuery } from "@zaflun/lumio-sdk";
import { useEffect } from "react";

function LiveLeaderboard() {
  const { data, refetch } = useQuery("getLeaderboard");

  // Refresh every 30 seconds
  useEffect(() => {
    const interval = setInterval(refetch, 30_000);
    return () => clearInterval(interval);
  }, [refetch]);

  return <List items={(data ?? []).map(...)} />;
}
```

---

## Configuration / lumio.config.json Reference

# `lumio.config.json` Reference

The manifest file at the root of every extension project. It defines the extension's identity, capabilities, and distribution settings.

## Full reference

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extensionId": "88b2478a-39c7-468e-bebd-14e52fd97ac0",
  "name": "Sports Scoreboard",
  "description": "Display live sports scores from ESPN on your stream overlay.",
  "category": "widget",
  "version": "1.2.0",
  "targets": ["editor", "layer"],
  "server": true,
  "permissions": ["chat:send"],
  "egress": {
    "allowHosts": ["site.api.espn.com", "cdn.espn.com"],
    "allowPorts": []
  },
  "fonts": ["Inter", "Roboto Mono"],
  "visibility": "public",
  "pricing": {
    "type": "free"
  },
  "config_schema": {
    "primaryColor": {
      "type": "color",
      "label": "Primary color",
      "default": "#6366f1"
    },
    "fontSize": {
      "type": "slider",
      "label": "Font size",
      "default": 16,
      "min": 8,
      "max": 72,
      "unit": "px"
    }
  }
}
```

## Fields

### `$schema`

| Type | Required |
|------|----------|
| `string` | No |

URL to the JSON Schema file for editor validation and autocompletion in VS Code. Always use:

```json
"$schema": "https://lumio.vision/schemas/lumio.config.schema.json"
```

This URL points to a live, dynamically generated JSON Schema served by the Lumio web app. It is NOT a static file — the schema is generated at runtime and reflects the current config format (including `triggers`, `platforms`, and `config_schema` fields).

The endpoint is CORS-open (`Access-Control-Allow-Origin: *`) so VS Code and other editors can fetch it for autocompletion and validation without authentication.

---

### `extensionId`

| Type | Required |
|------|----------|
| `string (UUID v4)` | Yes |

The unique identifier assigned to your extension when it was created via `lumio init` or the dashboard. It must be a valid UUID that exists in the Lumio database.

```json
"extensionId": "88b2478a-39c7-468e-bebd-14e52fd97ac0"
```

You cannot change this value after creation. The Extension-ID is how Lumio links your deployed bundle to your extension record.

---

### `name`

| Type | Required | Max length |
|------|----------|-----------|
| `string` | Yes | 255 characters |

The display name shown in the extension store and dashboard. Use title case. Keep it concise and descriptive.

```json
"name": "Sports Scoreboard"
```

---

### `description`

| Type | Required | Max length |
|------|----------|-----------|
| `string` | Yes | 1000 characters |

A short description of what the extension does. Used in the store listing and dashboard. Plain text only — no Markdown.

```json
"description": "Display live sports scores from ESPN on your stream overlay."
```

---

### `category`

| Type | Required |
|------|----------|
| `enum` | Yes |

The extension's primary category. Used for store filtering and browsing.

| Value | Description |
|-------|-------------|
| `"widget"` | Standalone visual element (scoreboard, timer, now playing) |
| `"extension"` | General-purpose extension that doesn't fit another category |
| `"overlay"` | Full-screen transparent layer overlay |
| `"bot_module"` | Chat bot command or moderation module |
| `"integration"` | External service connector (Discord, StreamElements) |
| `"theme"` | Visual style pack for overlays |

---

### `version`

| Type | Required |
|------|----------|
| `string (semver)` | Yes |

Semantic version of the extension. Must follow `MAJOR.MINOR.PATCH` format.

```json
"version": "1.2.0"
```

The version in `lumio.config.json` is the **source of truth** — `lumio deploy` reads it automatically. You can also override it with the `-v` flag.

---

### `targets`

| Type | Required |
|------|----------|
| `string[]` | Conditional |

Which surfaces the extension renders on. At least one target is required for widget, overlay, extension, integration, and theme categories. Bot module extensions (`category: "bot_module"`) have no visual surfaces and should omit this field or set it to an empty array.

```json
"targets": ["editor", "layer"]
```

| Value | Surface |
|-------|---------|
| `"editor"` | Dashboard sidebar panel |
| `"layer"` | Browser Source overlay |
| `"interactive"` | Standalone audience page |
| `"designer"` | Fullpage designer overlay with split pane |

---

### `server`

| Type | Required | Default |
|------|----------|---------|
| `boolean` | No | `false` |

Enable server functions. When `true`, the `server/` directory is bundled and deployed as server-side code.

```json
"server": true
```

---

### `permissions`

| Type | Required |
|------|----------|
| `string[]` | No |

Lumio service actions the extension needs. Shown to users at install time — users must grant consent. See [Permissions](/config/permissions) for the full list.

```json
"permissions": ["chat:send", "obs:set_scene"]
```

---

### `egress`

| Type | Required |
|------|----------|
| `object` | No |

Outbound network allowlist for `ctx.fetch()` in server actions. See [Egress](/config/egress).

```json
"egress": {
  "allowHosts": ["api.example.com", "*.example.com"],
  "allowPorts": [8443]
}
```

---

### `fonts`

| Type | Required |
|------|----------|
| `string[]` | No |

Google Fonts to preload for the extension. Font names must match the Google Fonts name exactly.

```json
"fonts": ["Inter", "Roboto Mono", "Press Start 2P"]
```

---

### `sounds`

| Type | Required | Default |
|------|----------|---------|
| `array` | No | `[]` |

Declare audio files to bundle with the extension. Bundled sounds are added to the user's sound library on install and removed on uninstall. Users cannot delete or rename them.

```json
"sounds": [
  { "file": "alert.mp3", "name": "Alert" },
  { "file": "chime.wav", "name": "Chime", "default_volume": 0.8 }
]
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `file` | `string` | Yes | Relative path in `dist/sounds/`. 1-255 characters. |
| `name` | `string` | Yes | Display name in the Sounds Panel. 1-255 characters. |
| `default_volume` | `number` | No | Default playback volume (0.0-1.0). |

Supported formats: MP3, WAV, OGG, WebM, M4A, AAC, FLAC. Default limit: 50 sounds per extension (admin-configurable). Place audio files in `dist/sounds/` before running `lumio deploy`.

---

### `visibility`

| Type | Required | Default |
|------|----------|---------|
| `enum` | No | `"private"` |

Controls who can see and install the extension.

| Value | Access |
|-------|--------|
| `"private"` | Only the developer can see and install |
| `"unlisted"` | Anyone with the direct link can install |
| `"public"` | Listed in the extension store |
| `"paid"` | Listed in the store, requires purchase (developer verification required) |

---

### `pricing`

| Type | Required | Default |
|------|----------|---------|
| `object` | No | `{ "type": "free" }` |

Pricing configuration. See [Pricing](/config/pricing) for details.

```json
"pricing": { "type": "free" }
```

---

### `config_schema`

| Type | Required |
|------|----------|
| `object` | No |

User-facing settings schema. Fields defined here appear in an auto-generated settings panel and are accessible via `useLumioConfig()`.

```json
"config_schema": {
  "primaryColor": {
    "type": "color",
    "label": "Primary color",
    "default": "#6366f1"
  },
  "showTimestamp": {
    "type": "boolean",
    "label": "Show timestamp",
    "default": true
  },
  "maxItems": {
    "type": "slider",
    "label": "Maximum items to show",
    "default": 5,
    "min": 1,
    "max": 50,
    "step": 1
  },
  "font": {
    "type": "font",
    "label": "Display font",
    "default": "Inter"
  },
  "displayOptions": {
    "type": "group",
    "label": "Display Options",
    "collapsed": true,
    "fields": {
      "opacity": {
        "type": "slider",
        "label": "Opacity",
        "default": 100,
        "min": 0,
        "max": 100,
        "unit": "%"
      }
    }
  }
}
```

#### Supported field types

| Type | Description | Key properties |
|------|-------------|----------------|
| `string` | Single-line text input | `placeholder` |
| `number` | Numeric input | `min`, `max`, `step` |
| `boolean` | Toggle switch | |
| `color` | Color picker with hex input | |
| `select` | Dropdown with predefined options | `options` |
| `textarea` | Multi-line text input | `placeholder`, `rows` |
| `slider` | Range slider | `min`, `max`, `step`, `unit` |
| `font` | Font family picker (Google Fonts) | |
| `icon` | Icon picker (Lucide, emoji, emotes, uploads) | |
| `image` | Image upload or URL | |
| `sound` | Sound picker — selects a sound from the account's sound library. Value is a UUID (sound ID). SchemaEditor renders a dropdown picker. | |
| `multiselect` | Multiple selection from options | `options`, `multiple` |
| `group` | Collapsible group of nested fields | `fields`, `collapsed` |
| `divider` | Visual separator (no value) | |
| `info` | Read-only informational text (no value) | `content` |
| `channel` | Multi-platform channel picker | |
| `designer` | Fullpage designer surface field | `presets` |

#### Common field properties

Every field type supports:

| Property | Type | Description |
|----------|------|-------------|
| `label` | `string` | Display label (required for all types) |
| `default` | varies | Default value |
| `required` | `boolean` | Whether the field must have a value |
| `visible_when` | `object` | Conditional visibility — show the field only when another field has a specific value |

#### Server-side validation

Config values are validated against your `config_schema` when users save settings — both through the dashboard and via the API. Invalid values are rejected with descriptive error messages.

| Check | Example |
|-------|---------|
| **Type match** | A `number` field rejects string values |
| **Required fields** | Fields with `required: true` must be present and non-null |
| **Select options** | `select` and `multiselect` fields only accept values from the declared `options` array |
| **Color format** | `color` fields must be valid `#RRGGBB` or `#RRGGBBAA` hex strings |
| **Slider range** | `slider` values must be within `min`/`max` bounds |
| **Unknown keys** | Keys not declared in `config_schema` are rejected |

Extensions can trust that `ctx.config` values match the declared types at runtime — the API enforces this before writing to the database.

#### The `sound` field type

A `sound` field lets users pick a sound from their account's sound library. The stored value is a UUID string (the sound ID) or `null` if no sound is selected. The SchemaEditor renders this as a dropdown populated with all sounds in the account's library, including extension-bundled sounds.

```json
{
  "config_schema": {
    "alertSound": {
      "type": "sound",
      "label": "Alert sound",
      "default": null
    }
  }
}
```

At runtime, `ctx.config.alertSound` holds the sound ID (UUID string) or `null`. Pass this ID to the `useLumioSound` hook to play the configured sound.

#### Auto-generated settings UI

Fields defined in `config_schema` are automatically rendered in a settings panel by the `SchemaEditor` component — no custom `editor.tsx` needed. Extensions can use `config_schema` alone, a custom `editor.tsx` alone, or both (schema fields render first, custom editor below).

---

### `designer_schema`

| Type | Required |
|------|----------|
| `array` | No |

An array of field definitions for the fullpage designer surface. The designer provides a split-pane view with a live preview alongside configuration fields. Fields use the same type system as `config_schema`.

```json
"designer_schema": [
  {
    "key": "layout",
    "type": "select",
    "label": "Layout",
    "default": "horizontal",
    "options": [
      { "value": "horizontal", "label": "Horizontal" },
      { "value": "vertical", "label": "Vertical" }
    ]
  }
]
```

Unlike `config_schema` (which is an object keyed by field name), `designer_schema` is an array where each entry includes a `key` property.

---

### `platforms`

| Type | Required |
|------|----------|
| `string[]` | Conditional |

Declares which chat platforms the extension supports. Required when `category` is `"bot_module"`, ignored for other categories.

```json
"platforms": ["twitch", "youtube", "kick"]
```

| Value | Platform |
|-------|---------|
| `"twitch"` | Twitch IRC chat |
| `"youtube"` | YouTube Live chat |
| `"kick"` | Kick chat |
| `"trovo"` | Trovo chat |
| `"discord"` | Discord (bot modules only) |

Bots only match triggers for extensions that support their platform. A Twitch-only extension does not receive YouTube messages.

Discord is restricted to bot module extensions — widget, overlay, and theme extensions cannot target Discord.

---

### `triggers`

| Type | Required |
|------|----------|
| `object` | No |

Defines when bot module handlers fire. Only allowed when `category` is `"bot_module"` — other categories with a `triggers` field are rejected at validation.

```json
"triggers": {
  "commands": [
    {
      "name": "points",
      "description": "Show your points balance",
      "cooldown_global": 5,
      "cooldown_user": 10,
      "min_role": "everyone"
    }
  ],
  "keywords": ["gg", "nice shot"],
  "patterns": ["https?://clips\\.twitch\\.tv/\\S+"],
  "events": ["twitch:subscribe", "twitch:raid"],
  "timers": [
    {
      "name": "reminder",
      "interval": 300,
      "handler": "periodicReminder"
    }
  ]
}
```

| Sub-field | Type | Description |
|-----------|------|-------------|
| `commands` | `array` | Chat commands with prefix matching. Max 20. |
| `keywords` | `string[]` | Substring matches. Min 3 chars each. Max 50. |
| `patterns` | `string[]` | Regex patterns. Max 200 chars each. Max 10. |
| `events` | `string[]` | Platform event types. |
| `timers` | `array` | Recurring handlers. Min 60s interval. |

See [Triggers](/config/triggers) for the full reference with validation rules and available event types.

---

## Configuration / Targets

# Targets

The `targets` field in `lumio.config.json` declares which surfaces your extension renders on. Only listed targets are bundled and deployed.

## Available targets

| Target | Surface | Entry file | Purpose |
|--------|---------|------------|---------|
| `"editor"` | Dashboard sidebar | `src/editor.tsx` | Configuration UI for the streamer |
| `"layer"` | Browser Source | `src/layer.tsx` | Transparent visual overlay on stream |
| `"interactive"` | Standalone page `/ext/{slug}` | `src/interactive.tsx` | Audience interaction page |
| `"designer"` | Fullpage designer overlay | `src/designer.tsx` | Split-pane designer with live preview |

## Common combinations

```json
{ "targets": ["editor", "layer"] }
```

The most common setup. The editor lets the streamer configure settings; the layer displays the overlay in the stream.

```json
{ "targets": ["editor"] }
```

Configuration-only. Useful for bot modules or integrations that have no visual overlay output.

```json
{ "targets": ["layer"] }
```

Layer-only widget. No custom editor UI — settings come from `config_schema` in `lumio.config.json` and the host auto-generates a settings panel. Most system extensions use this pattern.

```json
{ "targets": ["editor", "layer", "interactive"] }
```

Full extension with audience participation. Viewers can interact via the standalone page.

```json
{ "targets": ["editor", "interactive"] }
```

Interactive audience experience with editor configuration, but no overlay layer.

```json
{ "targets": ["layer", "designer"] }
```

Layer with a fullpage designer. The designer provides a split-pane view with live preview alongside configuration fields. Designer fields can be defined via `designer_schema` in `lumio.config.json` (host-side form) or via a custom `designer.tsx` using SDK Editor Components.

## Minimum requirement

At least one target is required. An extension with no targets is invalid.

## Entry files

Each listed target requires a corresponding entry file:

| Target | Required file | Called by |
|--------|--------------|-----------|
| `"editor"` | `src/editor.tsx` | Dashboard overlay editor sidebar |
| `"layer"` | `src/layer.tsx` | Browser Source iframe |
| `"interactive"` | `src/interactive.tsx` | Lumio webapp `/ext/{slug}` route |
| `"designer"` | `src/designer.tsx` | Fullpage designer overlay |

If a target is listed in `lumio.config.json` but the entry file is missing, the build fails with an error.

## Adding targets later

You can add targets to an existing extension by:
1. Adding the target to `"targets"` in `lumio.config.json`
2. Creating the corresponding entry file
3. Running `lumio build` and `lumio deploy`

Removing a target from `"targets"` removes the surface from the deployed bundle. Existing Browser Sources pointing to the removed layer surface will show an error until the user removes them.

---

## Configuration / Permissions

# Permissions

Extensions that need to trigger Lumio actions (send chat messages, control OBS scenes, emit events) must declare the required permissions in `lumio.config.json`.

## Declaring permissions

```json
{
  "permissions": ["chat:send", "obs:set_scene"]
}
```

Declared permissions are shown to users during installation. Users must explicitly grant consent before the extension can use them.

## Available permissions

| Permission | Action | Notes |
|------------|--------|-------|
| `"chat:send"` | Send a message to the platform chat | Message appears from the streamer's account or the bot |
| `"chat:read"` | Receive chat messages (for commands, keywords, patterns) | Required for bot modules that process chat |
| `"chat:delete"` | Delete a chat message by ID | Requires moderation rights on the platform. **Enhanced review.** |
| `"chat:ban"` | Ban or timeout a user | Requires moderation rights on the platform. **Enhanced review.** |
| `"obs:set_scene"` | Switch the active OBS scene | Requires OBS WebSocket to be connected |
| `"obs:set_source_visible"` | Show or hide an OBS source | Requires OBS WebSocket to be connected |
| `"obs:start_stream"` | Start the OBS stream | Requires OBS WebSocket to be connected |
| `"obs:stop_stream"` | Stop the OBS stream | Requires OBS WebSocket to be connected |
| `"sounds:play"` | Play or stop a sound in a browser source | Sound must exist in the account's sound library |
| `"events:emit"` | Emit a custom Lumio event | Triggers automations and other extensions listening for this event |
| `"overlay:update_layer"` | Toggle the visibility of another overlay layer | Must be on the same overlay |

## Using permissions

Request the permission with `useLumioAction()` in your extension:

```tsx
import { useLumioAction, Button } from "@zaflun/lumio-sdk";

function SendChatButton() {
  const { execute: sendChat, isLoading } = useLumioAction("chat:send");

  return (
    <Button
      label="Send to chat"
      onClick={() => sendChat({ message: "Game is starting!" })}
      disabled={isLoading}
    />
  );
}
```

The permission you declare is **exactly** the string you pass to `useLumioAction()` — each action maps to its own granular permission, and there are no coarse capability groupings (e.g. there is no `obs:control` that unlocks every OBS action; declare `obs:set_scene` to switch scenes, `obs:start_stream` to start the stream, and so on).

If the permission is not declared in `lumio.config.json`, the action call is rejected at runtime with a permission error.

## Admin review

Permissions are reviewed during the extension approval process. Reviewers check:
- Does the declared permission match the extension's stated purpose?
- Does the code actually use the declared permission?
- Are any undeclared permissions used in the code?

Extensions that declare permissions they do not use, or use permissions they did not declare, are rejected.

### Enhanced review

Permissions marked with **Enhanced review** (`chat:ban`, `chat:delete`) trigger additional manual code review during the store approval process. Reviewers verify that moderation logic is sound and cannot be exploited for mass-banning or mass-deletion. Extensions requesting these permissions may take longer to approve.

## User consent

When a user installs an extension that declares permissions:

1. The installation wizard shows a list of all requested permissions
2. The user must click **Grant permissions** to proceed
3. A user can revoke permissions later in the extension settings
4. If permissions are revoked, `useLumioAction()` calls return an error

## Future permissions

Additional permissions will be added as new Lumio actions are introduced. Check this page for updates. Custom permissions (for inter-extension communication via `events:emit`) use the standard `events:emit` permission with a custom event type.

---

## Configuration / Egress

# Egress

The `egress` field in `lumio.config.json` controls which external hosts your extension's server actions can make HTTP requests to via `ctx.fetch()`.

## Configuration

```json
{
  "egress": {
    "allowHosts": [
      "site.api.espn.com",
      "*.scdn.co",
      "api.openweathermap.org"
    ],
    "allowPorts": [8443]
  }
}
```

## Fields

### `allowHosts`

An array of allowed hostnames. Only hosts listed here can be reached from `ctx.fetch()`.

```json
"allowHosts": [
  "api.example.com",
  "*.example.com",
  "cdn.example.com"
]
```

**Wildcard support:** `*` matches any single subdomain level:

| Pattern | Matches | Does not match |
|---------|---------|---------------|
| `"api.example.com"` | `api.example.com` | `staging.api.example.com` |
| `"*.example.com"` | `api.example.com`, `cdn.example.com` | `example.com`, `a.b.example.com` |

### `allowPorts`

An optional array of additional allowed ports. Port 443 (HTTPS) is always allowed and does not need to be listed. HTTP (port 80) is never allowed.

```json
"allowPorts": [8443, 9443]
```

## Security rules

All `ctx.fetch()` calls are subject to these rules regardless of allowlist:

| Rule | Description |
|------|-------------|
| **HTTPS only** | HTTP is blocked. All requests must use `https://` |
| **No private IPs** | RFC 1918 ranges and loopback are blocked |
| **No DNS rebinding** | Hostnames must resolve to public IPs |
| **30s timeout** | Requests exceeding 30 seconds are cancelled |
| **10 requests/invocation** | Maximum 10 `ctx.fetch()` calls per action run |
| **4 MB response limit** | Response bodies larger than 4 MB are truncated |

## Common patterns

### External sports API

```json
{
  "egress": {
    "allowHosts": ["site.api.espn.com", "cdn.espn.com"]
  }
}
```

### Weather service

```json
{
  "egress": {
    "allowHosts": ["api.openweathermap.org"]
  }
}
```

### Spotify album art

```json
{
  "egress": {
    "allowHosts": ["i.scdn.co", "*.scdn.co"]
  }
}
```

### Webhook delivery

```json
{
  "egress": {
    "allowHosts": ["discord.com", "hooks.slack.com"]
  }
}
```

## Review

The egress allowlist is reviewed during extension approval. Reviewers check:
- Do the declared hosts match the extension's stated purpose?
- Are wildcards appropriately scoped?
- Are the hosts known, reputable services?

Overly broad allowlists (e.g., `"*.com"`) or allowlists that include analytics/tracking services not needed for the extension's function will result in rejection with a request to narrow the scope.

---

## Configuration / Pricing

# Pricing

The `pricing` field in `lumio.config.json` controls how your extension is monetized in the Lumio Extension Store.

## Free

No purchase required. Anyone can install the extension at no cost.

```json
{
  "pricing": {
    "type": "free"
  }
}
```

## One-time purchase

Users pay once to unlock the extension permanently.

```json
{
  "pricing": {
    "type": "one_time",
    "amount": 4.99,
    "currency": "EUR"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `type` | `"one_time"` | One-time payment |
| `amount` | `number` | Price in the specified currency |
| `currency` | `"EUR"` | Currency code (currently EUR only) |

## Subscription

Users pay a recurring monthly fee.

```json
{
  "pricing": {
    "type": "subscription",
    "amount": 2.99,
    "currency": "EUR",
    "interval": "monthly"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `type` | `"subscription"` | Recurring payment |
| `amount` | `number` | Price per billing interval |
| `currency` | `"EUR"` | Currency code (currently EUR only) |
| `interval` | `"monthly"` | Billing interval (monthly only) |

## Revenue share

Lumio takes a **30% platform fee** on all paid transactions. Developers receive **70%** of each payment.

| Pricing type | Developer receives |
|-------------|-------------------|
| Free | — |
| One-time €4.99 | €3.49 per purchase |
| Monthly €2.99 | €2.09 per billing cycle |

Payouts are processed monthly via Stripe Connect, PayPal, or SEPA bank transfer. See [Payout Settings](/account/payout-settings) for minimum payout thresholds.

## Developer verification required

Paid extensions (`one_time` or `subscription` pricing) require **developer verification** before the extension can be published. Verification includes:
- Identity verification (personal or business)
- Tax ID (for EU VAT compliance)
- Payout method setup (Stripe Connect, PayPal, or SEPA)

See [Verification](/publishing/verification) for the full process.

## Changing pricing

You can change pricing between versions. The new pricing takes effect for new installations. Existing subscribers are not automatically moved to a new plan — they continue on the plan they purchased.

Changing from paid to free: existing purchases remain valid, new users get it free.
Changing from free to paid: existing installations remain unlocked for existing users.

---

## Configuration / Triggers

# Triggers

The `triggers` field in `lumio.config.json` defines when your bot module handlers fire. Triggers are only allowed when `category` is `"bot_module"` — other extension categories with a `triggers` field are rejected at validation.

## Overview

```json
{
  "category": "bot_module",
  "triggers": {
    "commands": [...],
    "keywords": [...],
    "patterns": [...],
    "events": [...],
    "timers": [...]
  }
}
```

Each trigger type has different matching behavior and execution characteristics:

| Trigger | Where matched | Execution | Latency |
|---------|---------------|-----------|---------|
| Command | Bot (prefix match) | Sync HTTP (500ms deadline) | ~50-200ms |
| Keyword | Bot (substring) | Async (fire-and-forget) | Fire-and-forget |
| Pattern | Bot (compiled regex) | Async (fire-and-forget) | Fire-and-forget |
| Event | Worker (event subscription) | Async | Fire-and-forget |
| Timer | Worker (internal clock) | Async (self-triggered) | N/A |

## Commands

Chat commands triggered by a prefix (e.g., `!points`).

```json
{
  "triggers": {
    "commands": [
      {
        "name": "points",
        "description": "Show your current points balance",
        "cooldown_global": 5,
        "cooldown_user": 10,
        "min_role": "everyone"
      }
    ]
  }
}
```

### Command fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Command name (without `!` prefix). Alphanumeric + underscore, 1-32 characters. |
| `description` | `string` | Yes | Short description shown in the dashboard and Discord slash command registration. |
| `cooldown_global` | `integer` | No | Global cooldown in seconds (0 = no cooldown). Applies to all users. |
| `cooldown_user` | `integer` | No | Per-user cooldown in seconds (0 = no cooldown). Applies individually. |
| `min_role` | `string` | No | Minimum role required to use the command. Default: `"everyone"`. |
| `discord_options` | `array` | No | Discord slash command options. Ignored on other platforms. See [Discord Slash Commands](/guides/discord-slash-commands). |

### Command validation rules

| Rule | Constraint |
|------|-----------|
| Name format | `^[a-zA-Z0-9_]+$`, 1-32 characters |
| Max commands per extension | 20 |
| Cooldown values | Integer >= 0 |

### `min_role` values

| Value | Who can use |
|-------|------------|
| `"everyone"` | All viewers |
| `"follower"` | Followers and above |
| `"subscriber"` | Subscribers and above |
| `"vip"` | VIPs and above |
| `"moderator"` | Moderators and above |
| `"broadcaster"` | Broadcaster only |

Users can raise (but not lower) the minimum role in their dashboard override settings.

## Keywords

Substring matches against chat messages. When a keyword appears anywhere in a message, the associated handler fires.

```json
{
  "triggers": {
    "keywords": ["gg", "nice shot", "pog"]
  }
}
```

### Keyword validation rules

| Rule | Constraint |
|------|-----------|
| Minimum length | 3 characters |
| Max keywords per extension | 50 |

Keywords are matched as case-insensitive substrings. A keyword of `"gg"` matches `"gg wp"`, `"lol gg"`, and `"gg"`.

## Patterns

Regex patterns matched against chat messages. When a pattern matches, the handler receives the matched string.

```json
{
  "triggers": {
    "patterns": ["https?://clips\\.twitch\\.tv/\\S+"]
  }
}
```

### Pattern validation rules

| Rule | Constraint |
|------|-----------|
| Max length | 200 characters |
| Max patterns per extension | 10 |
| Regex engine | Rust `regex` crate (linear-time, no backreferences) |
| ReDoS safety | Guaranteed by construction (Rust regex crate) |

Pattern matching runs in Rust on the bot side. JavaScript `RegExp` is never used for trigger matching. The matched substring is passed to the handler as the `matched` parameter:

```typescript
import { pattern } from "@zaflun/lumio-sdk/server";

export const clipLogger = pattern(
  "https?://clips\\.twitch\\.tv/\\S+",
  async (ctx, message, matched) => {
    // matched = "https://clips.twitch.tv/FunnyClip123"
    return { reply: `Clip from ${ctx.user.name}: ${matched}` };
  }
);
```

## Events

Platform events that trigger handlers when they occur.

```json
{
  "triggers": {
    "events": ["twitch:subscribe", "twitch:raid", "youtube:superchat"]
  }
}
```

Each event type must be a valid Lumio event type. The handler receives the event payload:

```typescript
import { event } from "@zaflun/lumio-sdk/server";

export const welcomeSub = event("twitch:subscribe", async (ctx, evt) => {
  return { reply: `Welcome ${evt.user_name}!` };
});
```

### Available event types

**Twitch:** `twitch:follower`, `twitch:subscribe`, `twitch:gift_sub`, `twitch:resub`, `twitch:cheer`, `twitch:raid`, `twitch:reward`, `twitch:hype_train`, `twitch:hype_train_end`, `twitch:poll`, `twitch:poll_end`, `twitch:prediction`, `twitch:prediction_lock`, `twitch:prediction_end`, `twitch:goal`, `twitch:goal_end`, `twitch:ad_break`, `twitch:ban`, `twitch:unban`, `twitch:stream_online`, `twitch:stream_offline`, `twitch:stream_update`

**YouTube:** `youtube:subscribe`, `youtube:member`, `youtube:superchat`, `youtube:supersticker`, `youtube:gift_membership`, `youtube:gift_membership_received`, `youtube:poll`

**Kick:** `kick:follower`, `kick:subscribe`, `kick:gift`, `kick:stream_online`, `kick:stream_offline`

**Trovo:** `trovo:subscribe`, `trovo:spell`

**Spotify:** `spotify:track`, `spotify:play`, `spotify:pause`, `spotify:skip`, `spotify:volume`, `spotify:queue_add`, `spotify:device`, `spotify:playlist_add`, `spotify:playlist_remove`, `spotify:playlist_create`, `spotify:playlist_edit`, `spotify:playlist_delete`

**StreamElements:** `streamelements:tip`

**Chat:** `twitch:chat`, `youtube:chat`, `kick:chat`, `trovo:chat`, `chat:message`

## Timers

Recurring handlers that fire at a fixed interval.

```json
{
  "triggers": {
    "timers": [
      {
        "name": "reminder",
        "interval": 300,
        "handler": "periodicReminder"
      },
      {
        "name": "adDisclaimer",
        "interval": 1800,
        "handler": "adMessage"
      }
    ]
  }
}
```

### Timer fields

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | `string` | Yes | Unique identifier for this timer |
| `interval` | `integer` | Yes | Firing interval in seconds (minimum: 60) |
| `handler` | `string` | Yes | Name of the exported server function to call |

### Timer validation rules

| Rule | Constraint |
|------|-----------|
| Minimum interval | 60 seconds |
| Handler | Must match an exported server function name |

### Timer behavior

- Timers are per-install, not per-account. Two accounts installing the same extension have independent timers.
- Timer messages are sent to all declared platforms that the account has active bot connections for.
- If a platform bot is offline, the timer action for that platform is silently dropped. There is no retry — timers are best-effort.
- Users can override the interval and enable/disable individual timers in their dashboard.

## Moderation

The `moderate()` handler does not need a trigger declaration — it runs on every message that passes built-in module checks. Declare it only in your handler code:

```typescript
import { moderate } from "@zaflun/lumio-sdk/server";

export const linkFilter = moderate(async (ctx, message) => {
  if (message.text.includes("banned-site.com")) {
    return { block: true, action: "timeout", duration: 60, reason: "Banned link" };
  }
  return { block: false };
});
```

Moderation handlers use the sync execution path (500ms deadline). They require the `chat:ban` or `chat:delete` permission, which triggers enhanced manual review during store approval.

---

## CLI / Install

# Installing the Lumio CLI

## npm (global)

```bash
npm install -g @zaflun/lumio-cli
```

## pnpm (global)

```bash
pnpm add -g @zaflun/lumio-cli
```

## npx (without installing)

```bash
npx @zaflun/lumio-cli login
npx @zaflun/lumio-cli init my-extension
```

## Verify installation

```bash
lumio --version
# 2026.5.1
```

## System requirements

| Requirement | Version |
|-------------|---------|
| Node.js | 22.13 or higher |
| npm | 10+ (or pnpm 9+) |
| OS | Linux, macOS, Windows |

## Updating

```bash
npm install -g @zaflun/lumio-cli@latest
```

## Available commands

| Command | Description |
|---------|-------------|
| `lumio login` | Authenticate with your Lumio account |
| `lumio logout` | Remove stored credentials |
| `lumio whoami` | Show current authenticated user |
| `lumio init` | Create a new extension project |
| `lumio dev` | Start the development server |
| `lumio build` | Build the extension bundle |
| `lumio deploy` | Deploy a built extension |
| `lumio env` | Manage extension secrets |
| `lumio run` | Run a server function locally |
| `lumio status` | Show current review status |
| `lumio logs` | Stream server function logs |
| `lumio dashboard` | Open the extension dashboard in a browser |

Run `lumio --help` or `lumio <command> --help` for command-specific help.

---

## CLI / lumio login

# `lumio login`

Authenticate with your Lumio account. Credentials are stored in `~/.lumio/credentials` and reused automatically for subsequent commands.

## Usage

```bash
lumio login [--token <token>] [--api-url <url>] [--id-url <url>] [--port <port>]
```

## Options

| Flag | Default | Description |
|------|---------|-------------|
| `--token <token>` | — | Authenticate with a Lumio API key directly (no browser) |
| `--api-url <url>` | `https://api.lumio.vision` | API base URL for the token exchange |
| `--id-url <url>` | `https://id.lumio.vision` | ID (login) app URL the browser is opened against |
| `--port <port>` | `9876` | Local loopback port that receives the PKCE callback |

## Browser-based login (default)

```bash
lumio login
```

This opens your default browser to the Lumio ID app login page (`https://id.lumio.vision/login`) using the **PKCE flow** shared by all native apps (see [PKCE & Native App Auth](https://docs.lumio.vision/developer-guide/pkce-native-auth)). The CLI:

1. Generates a PKCE `code_verifier` / `code_challenge` (S256) and a random `state`, then starts a loopback HTTP server on `http://localhost:9876/callback`.
2. Opens the browser to `https://id.lumio.vision/login?client_type=cli&code_challenge=…&code_challenge_method=S256&redirect_uri=http://localhost:9876/callback&state=…`.
3. You sign in with a provider (Twitch, Discord, Google). The ID app mints a single-use authorization code (`lumio_auth_…`) and redirects your browser back to the loopback callback with `?code=…&state=…`.
4. The CLI validates `state`, then exchanges the code and the original `code_verifier` at `POST {api-url}/v1/auth/token/exchange` for a Lumio JWT + refresh token, which it stores in `~/.lumio/credentials`.

The flow needs no client secret — PKCE (Proof Key for Code Exchange) protects the code in transit, which is safe for CLI tools. The callback binds to loopback only, so no other host on the network can receive the code.

> **Session lifetime:**
> The browser flow yields a **short-lived JWT** (~15 min) plus a long-lived refresh token (both stored in `~/.lumio/credentials`). For long-running, non-interactive use (CI/CD, scripts), prefer a durable `lm_usr_*` API key via `--token` / `LUMIO_TOKEN`.
:::caution Self-hosted / non-production deployments
The ID app only redirects the auth code to a `redirect_uri` present in its `ALLOWED_REDIRECT_ORIGINS` allowlist. Production allowlists the CLI loopback origin (`http://localhost:9876`); a self-hosted ID app must add the origin you pass via `--port` to `ALLOWED_REDIRECT_ORIGINS`, or the browser login fails with *"redirect_uri missing or not allowed"*.
:::

## Token-based login (pre-provisioned token)

For non-interactive environments where a browser is not available, pass a pre-provisioned Lumio API token:

```bash
lumio login --token lm_usr_xxxxxxxxxxxx
```

Or set the `LUMIO_TOKEN` environment variable:

```bash
LUMIO_TOKEN=lm_usr_xxxxxxxxxxxx lumio deploy -v 1.0.0
```

The `LUMIO_TOKEN` environment variable takes precedence over stored credentials.

## Getting a token

1. Open [lumio.vision](https://lumio.vision) in your browser
2. Navigate to **Dashboard → API Keys**
3. Click **Create API key**
4. Give it a name (e.g., "CI/CD pipeline")
5. Copy the generated key — it starts with `lm_usr_`

## Checking your credentials

```bash
lumio whoami
# Logged in as: Your Name (raphael@example.com)
# Account: your-account-slug
```

## Logging out

```bash
lumio logout
# Credentials removed from ~/.lumio/credentials
```

## Credential storage

Credentials are stored in `~/.lumio/credentials` as a JSON file (`0600`, in a `0700` directory). Browser login writes the JWT `token`, its `refresh_token`, and `expires_at`; token login writes just the `token` (your `lm_usr_*` API key). It is not encrypted at rest — keep your home directory secure.

---

## CLI / lumio init

# `lumio init`

Create a new extension project. Runs an interactive wizard that registers the extension with Lumio (generating an Extension-ID), scaffolds the project files, and writes `lumio.config.json`.

## Usage

```bash
lumio init [project-name]
```

## Example

```bash
lumio init my-scoreboard
```

If `project-name` is omitted, the wizard asks for it.

## Interactive wizard

The wizard asks:

```
? Extension name: My Scoreboard
? Description: Display live sports scores on your stream overlay
? Category:
  widget
  extension
  overlay
  bot_module
  integration
  theme
? Template:
  Blank
  Widget (editor + layer)
  Full-Stack Widget (editor + layer + server functions)
  Interactive Game (editor + layer + interactive + server)
  Bot Module (editor + server)
  Integration (editor + server)
  Theme (layer only)
? Targets: (check all that apply)
  [x] editor
  [x] layer
  [ ] interactive
? Enable server functions: No
? Initial visibility: private
```

After completing the wizard:

1. The extension is **registered with Lumio** (creates the extension record, generates a UUID Extension-ID)
2. A project directory is created with the scaffolded files
3. `lumio.config.json` is written with the `extensionId` from Lumio
4. Dependencies are listed in `package.json` (not installed automatically — run `pnpm install`)

## Templates

| Template | Files created | Targets | Server |
|----------|--------------|---------|--------|
| Blank | `editor.tsx` (or as selected) | Chosen in wizard | No |
| Widget | `editor.tsx`, `layer.tsx` | editor, layer | No |
| Full-Stack Widget | `editor.tsx`, `layer.tsx`, `server/schema.ts`, `server/functions.ts` | editor, layer | Yes |
| Interactive Game | All four entry files + server | editor, layer, interactive | Yes |
| Bot Module | `editor.tsx`, server files | editor | Yes |
| Integration | `editor.tsx`, server files | editor | Yes |
| Theme | `layer.tsx` | layer | No |

## Generated files

```
my-scoreboard/
├── lumio.config.json       <- Extension manifest
├── package.json            <- @zaflun/lumio-sdk + react dependencies
├── tsconfig.json           <- TypeScript config
└── src/
    ├── editor.tsx          <- Editor surface entry
    └── layer.tsx           <- Layer surface entry
```

For templates with server functions, also:

```
my-scoreboard/
└── server/
    ├── schema.ts           <- defineSchema + defineTable
    └── functions.ts        <- queryRows / action exports
```

## Options

| Flag | Description |
|------|-------------|
| `--template <name>` | Skip template selection, use named template |
| `--no-install` | Skip prompting (non-interactive mode, for scripting) |

---

## CLI / lumio dev

# `lumio dev`

Start the development server with hot-reload and a Lumio sandbox environment.

## Usage

```bash
lumio dev [--port <port>]
```

## What it does

1. Starts a **Vite dev server** for each target surface defined in `lumio.config.json`
2. Opens a **Lumio sandbox** — a browser window that simulates the host environment (dashboard editor, layer, or interactive page)
3. Watches for file changes and hot-reloads the affected surfaces
4. Connects to the **Lumio API** for real storage, events, and server function execution

## Example

```bash
cd my-extension
pnpm install
lumio dev
```

```
 Lumio Dev Server
 Extension: Sports Scoreboard (88b2478a...)
 Surfaces: editor, layer

 editor   → http://localhost:3005/editor
 layer    → http://localhost:3005/layer

 Sandbox: http://localhost:3005
 Press Ctrl+C to stop
```

## Sandbox features

The sandbox simulates the host environment with these features:

| Feature | Description |
|---------|-------------|
| **Mock events** | Send test events (twitch:follower, twitch:subscribe, etc.) via the sandbox UI |
| **Storage panel** | View and edit `useExtensionStorage()` values in real time |
| **Surface switching** | Switch between editor, layer, and interactive views |
| **Real server functions** | Server functions run against the actual staging Lumio API |
| **Console forwarding** | `console.log` output from the extension appears in the terminal |

## Options

| Flag | Default | Description |
|------|---------|-------------|
| `--port <port>` | `3005` | Port for the dev server |
| `--no-open` | — | Don't automatically open the sandbox in the browser |

## Hot reload

File changes trigger automatic hot-reload:
- `src/*.tsx` changes — instant hot module replacement (HMR), no full page reload
- `server/*.ts` changes — server functions re-bundle and restart
- `lumio.config.json` changes — dev server restarts

## Testing events

Use the **Events** panel in the sandbox to fire test events:

```
[Sandbox] Events panel:
  twitch:follower    → [Fire]  userName: "TestViewer"
  twitch:subscribe   → [Fire]  tier: "1000", months: 3
  spotify:track      → [Fire]  title: "Lo-Fi Beats", artist: "ChilledCow"
  chat:message       → [Fire]  message: "Hello world!"
```

Click **Fire** to trigger the event and see your extension react in real time.

## Using a specific environment

The dev server connects to the staging Lumio API by default. To connect to a local API instance:

```bash
LUMIO_API_URL=http://localhost:8080 lumio dev
```

---

## CLI / lumio build

# `lumio build`

Build the extension bundle for deployment. Produces optimized client bundles for each surface and a source archive.

## Usage

```bash
lumio build [--outdir <path>]
```

## What it produces

After a successful build, the `dist/` directory (or custom `--outdir`) contains per-target bundles and an optional `assets/` directory for referenced static files:

```
dist/
├── editor.js                  <- Editor surface bundle
├── layer.js                   <- Layer surface bundle
├── styles.css                 <- Combined CSS (Tailwind or plain)
├── assets/                    <- Static assets referenced by components
│   ├── logo-a1b2c3.png
│   ├── font-d4e5f6.woff2
│   └── animation-g7h8i9.lottie
├── server/                    <- Only if server: true
│   └── functions.[hash].js   <- Server bundle (ESM)
└── source.tar.gz              <- Source archive (required by review process)
```

### Asset handling

Images, fonts, videos, and other static files imported in your code are automatically copied to `assets/` with a content hash in the filename. esbuild handles this via file loaders:

| File type | Output pattern |
|-----------|---------------|
| `.png`, `.jpg`, `.gif`, `.svg`, `.webp`, `.avif`, `.ico` | `assets/[name]-[hash].[ext]` |
| `.woff`, `.woff2`, `.ttf`, `.otf`, `.eot` | `assets/[name]-[hash].[ext]` |
| `.mp4`, `.webm`, `.ogg`, `.mp3`, `.wav` | `assets/[name]-[hash].[ext]` |
| `.json`, `.lottie` | `assets/[name]-[hash].[ext]` |

Import assets in your components and the bundler resolves the correct URL at runtime:

```tsx
import logoUrl from "./assets/logo.png";

export default function Layer() {
  return <img src={logoUrl} alt="Logo" />;
}
```

## Example

```bash
lumio build
```

```
Building Sports Scoreboard v1.2.0...

  editor   525 KB  (153 KB gzipped)
  layer    312 KB  (98 KB gzipped)
  server   44 KB

  source.tar.gz  assembled

Build complete → dist/
```

## Options

| Flag | Description |
|------|-------------|
| `--outdir <path>` | Output directory (default: `dist`) |
| `--no-source` | Skip generating `source.tar.gz` (not recommended) |

## CSS and Styling

`lumio build` supports three styling approaches. You choose during `lumio init`, but can switch at any time.

### Tailwind CSS v4 (recommended)

If `src/globals.css` contains `@import "tailwindcss"`, the build compiles it via the Tailwind CLI before bundling. Use any Tailwind utility classes in your components:

```tsx
export default function Layer() {
  return (
    <div className="flex items-center gap-2 bg-black/80 rounded-lg p-4">
      <span className="text-white text-sm font-medium">Hello</span>
    </div>
  );
}
```

Requires `tailwindcss` as a dev dependency (`npm add -D tailwindcss@^4.3`).

### Plain CSS

Create `src/globals.css` (or `src/style.css`) with regular CSS. The file is copied to `dist/styles.css`:

```css
.my-widget {
  background: rgba(0, 0, 0, 0.8);
  border-radius: 8px;
  padding: 16px;
}
```

Import it in your component: `import "./globals.css";`

### Inline styles

No CSS files needed. Style directly via React `style` props:

```tsx
export default function Layer() {
  return <div style={{ background: "rgba(0,0,0,0.8)", padding: 16 }}>Hello</div>;
}
```

## Source archive

`source.tar.gz` contains the full source code of your extension (excluding `node_modules` and `dist`). It is uploaded alongside the bundle during `lumio deploy` and made available to reviewers.

> ****`CHANGELOG.md` must include an entry for the version being built.** If no entry is found for the current version in `lumio.config.json`, the CLI prints a warning — the build still succeeds, but release notes will be empty unless you fill them in via the submission wizard.:**
> 
## TypeScript errors

The build fails on TypeScript errors. To check for errors without building:

```bash
npx tsc --noEmit
```

## Bundle size limits

| Plan | Max bundle size per surface |
|------|-----------------------------|
| Free | 10 MB |
| Pro | 50 MB |

If a surface bundle exceeds the limit, the build fails with an error. Optimize with dynamic imports or reduce dependencies.

---

## CLI / lumio deploy

# `lumio deploy`

Upload a built extension bundle to Lumio as a new version. The version starts in `draft` status and must go through the submission wizard to enter the review process.

## Usage

```bash
lumio deploy [-v <version>] [-d <description>] [--breaking] [--draft] [--token <token>]
```

## Example

```bash
# Build first, then deploy
lumio build
lumio deploy -v 1.2.0 -d "Added live score updates from ESPN"
```

Or let it read the version from `lumio.config.json` automatically:

```bash
lumio deploy -d "Fixed score display alignment"
```

## Options

| Flag | Alias | Description |
|------|-------|-------------|
| `--version <semver>` | `-v` | Version string (default: reads from `lumio.config.json`) |
| `--description <text>` | `-d` | Release notes / changelog for this version |
| `--breaking` | — | Flag this version as a breaking change (disables auto-update for existing installs) |
| `--draft` | — | Upload as draft without triggering the submission flow (default behavior — this flag is explicit) |
| `--token <token>` | — | API token for authentication (skips interactive login). Also reads from `LUMIO_TOKEN` env var |
| `--outdir <path>` | — | Location of the built bundle (default: `dist`) |

## Pre-flight checks

Before uploading, the CLI runs these validation checks:

1. **Sound file format** — each file in `dist/sounds/` is validated against the supported audio formats (MP3, WAV, OGG, WebM, M4A, AAC, FLAC) and checked for existence
2. **Sound count** — the number of sound files is checked against the resolved `max_sounds` limit (fetched from the API via `GET /v1/developer/extensions/{id}/limits`)
3. **Per-file size** — each sound file is checked against the resolved `max_sound_file_size` limit
4. **Total storage** — the combined size of all sound files is checked against the resolved `max_sound_storage_bytes` limit
5. **Manifest validation** — `lumio.config.json` is validated against the extension schema

If any check fails, the deploy is blocked with a descriptive error message.

## What happens on deploy

1. CLI reads `lumio.config.json` and validates the extension
2. All built files from `dist/` are collected (JS, CSS, HTML, images, fonts, video, audio, JSON, Lottie, source maps)
3. Sound files placed in `dist/sounds/` are registered as extension-bundled sounds — they appear in the account's sound library when the extension is installed
4. Each file is uploaded individually as a multipart `files` field alongside `source.tar.gz`, manifest, and release notes
5. A new `ExtensionVersion` record is created with status `draft`
6. Files are stored via `lo-storage` (S3/R2/local) at `{extension_id}/versions/{version}/{file_path}`
7. Each file gets a row in `extension_version_files` with content-type, size, and content hash

### Supported file types

| Category | Extensions |
|----------|-----------|
| Code | `.js`, `.css`, `.html`, `.map` |
| Images | `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, `.webp`, `.avif`, `.ico` |
| Video/Audio | `.mp4`, `.webm`, `.ogg`, `.mp3`, `.wav` |
| Fonts | `.woff`, `.woff2`, `.ttf`, `.otf`, `.eot` |
| Data | `.json`, `.lottie` |

### Size limits

| Limit | Value |
|-------|-------|
| Per file | 10 MB |
| Total upload | 50 MB |
| Max files per version | 200 |

```
Deploying Sports Scoreboard v1.2.0...

  Uploading 8 files (1.2 MB total)...
    layer.js         312 KB  application/javascript
    editor.js        525 KB  application/javascript
    styles.css        24 KB  text/css
    assets/logo.png   89 KB  image/png
    ...
  Upload successful. Status: draft
  Submit for review via the dashboard or `lumio status`.
```

### Backward compatibility

Older CLI versions that send a single `bundle` field continue to work. The API treats the single bundle as `bundle.js` and processes it through the same pipeline.

## CI/CD deployment

In CI environments, authenticate with either the `LUMIO_TOKEN` environment variable or the `--token` flag:

```bash
# Via environment variable
LUMIO_TOKEN=${{ secrets.LUMIO_TOKEN }} lumio deploy -v 1.2.0 -d "Automated release"

# Via --token flag
lumio deploy -v 1.2.0 -d "Automated release" --token ${{ secrets.LUMIO_TOKEN }}
```

The CLI detects `CI=true` and skips interactive prompts. When `--token` is provided, it takes precedence over the stored credential.

## Breaking changes

Mark a version as breaking to prevent auto-updates for users who have not manually reviewed the breaking change notes:

```bash
lumio deploy -v 2.0.0 --breaking -d "Storage format changed — manual migration required"
```

Breaking versions show a notice in the extension store and require users to manually accept the update.

## Exit codes

| Exit code | Meaning |
|-----------|---------|
| `0` | Deployment succeeded |
| `1` | Authentication error (run `lumio login`) |
| `2` | Validation error (missing build, invalid version, etc.) |
| `3` | Upload error (network failure, rate limit) |
| `4` | Extension not found (invalid Extension-ID) |

---

## CLI / lumio status

# `lumio status`

Show the review status of your extension's latest deployed version.

## Usage

```bash
lumio status [--version <semver>]
```

## Example

```bash
lumio status
```

```
Sports Scoreboard v1.2.0
Status: testing

  Submitted:     2026-05-10 14:32 UTC
  In review:     2026-05-11 09:15 UTC
  Testing since: 2026-05-12 11:00 UTC

  Testers: 3 active
  Feedback: 2 messages (open dashboard to view)

  Next: Publish when testing is complete
  Dashboard: https://lumio.vision/dashboard/extensions/88b2478a.../versions/1.2.0
```

## Options

| Flag | Description |
|------|-------------|
| `--version <semver>` | Check a specific version (default: latest) |
| `--json` | Output machine-readable JSON |

## Version status lifecycle

| Status | Description |
|--------|-------------|
| `draft` | Uploaded but not yet submitted for review |
| `pending_review` | Submitted, waiting for an admin reviewer |
| `in_review` | An admin is actively reviewing the extension |
| `testing` | Approved for testing; testers can install it |
| `pending_publish` | Testing complete; awaiting final publish approval |
| `published` | Live in the extension store |
| `rejected` | Review failed — see rejection reason in dashboard |

## JSON output

```bash
lumio status --json
```

```json
{
  "extensionId": "88b2478a-39c7-468e-bebd-14e52fd97ac0",
  "name": "Sports Scoreboard",
  "version": "1.2.0",
  "status": "testing",
  "submittedAt": "2026-05-10T14:32:00Z",
  "reviewStartedAt": "2026-05-11T09:15:00Z",
  "testingStartedAt": "2026-05-12T11:00:00Z",
  "publishedAt": null,
  "rejectedAt": null,
  "rejectionReason": null,
  "testerCount": 3,
  "feedbackCount": 2
}
```

## Checking all versions

```bash
lumio status --version 1.1.0
lumio status --version 1.2.0
```

Or view the full version history in the extension dashboard.

---

## CLI / lumio logs

# `lumio logs`

Stream server function logs in real time (or fetch historical logs). Useful for debugging production server functions.

## Usage

```bash
lumio logs [--follow] [--since <time>] [--level <level>] [--version <semver>]
```

## Example

```bash
# Stream logs in real time
lumio logs --follow

# Show last hour of logs
lumio logs --since 1h

# Show only errors
lumio logs --level error
```

```
[2026-05-12T10:34:12Z] [info]  getScoreboard called: sport=football league=nfl
[2026-05-12T10:34:12Z] [info]  ESPN API response: 200 OK (342ms)
[2026-05-12T10:34:13Z] [info]  getScoreboard returned 8 events
[2026-05-12T10:34:45Z] [error] addRule failed: text field is required (installation: abc123)
[2026-05-12T10:35:01Z] [warn]  rate limit approaching: castVote 45/50 calls this minute
```

## Options

| Flag | Description |
|------|-------------|
| `--follow` | Stream logs in real time (like `tail -f`). Press Ctrl+C to stop |
| `--since <time>` | Show logs from this time ago. Accepts `5m`, `1h`, `24h`, `7d` |
| `--level <level>` | Filter by log level: `debug`, `info`, `warn`, `error` |
| `--version <semver>` | Show logs only for a specific version |
| `--json` | Output machine-readable JSON (one JSON object per line) |
| `--limit <n>` | Maximum number of log lines to fetch (default: 100) |

## Log levels

| Level | When it appears |
|-------|----------------|
| `debug` | `console.debug()` calls in server functions |
| `info` | `console.log()` and `console.info()` calls |
| `warn` | `console.warn()` calls and SDK rate limit warnings |
| `error` | Uncaught exceptions, rejected actions, timeout errors |

## Filtering by installation

Use `--installation <id>` to see logs from a specific overlay installation:

```bash
lumio logs --installation abc123def456 --follow
```

The installation ID is visible in the extension dashboard under **Installations**.

## JSON format

```bash
lumio logs --json --limit 5
```

```json
{"timestamp":"2026-05-12T10:34:12Z","level":"info","function":"getScoreboard","message":"ESPN API response: 200 OK (342ms)","installationId":"abc123"}
{"timestamp":"2026-05-12T10:34:45Z","level":"error","function":"addRule","message":"text field is required","installationId":"abc123"}
```

## Notes

- Logs are retained for **30 days**
- Logs are only available for server functions (`server: true`) — client-side extensions have no server logs
- `console.log()` calls in server functions appear as `info` level
- Sensitive values (secrets, user data) are automatically redacted in logs

---

## Publishing / Store Listing

# Store Listing

The store listing is the public face of your extension in the Lumio Extension Store. It consists of a name, description, icon, screenshots, and category. You manage it in the extension dashboard.

## Listing fields

| Field | Requirements | Notes |
|-------|-------------|-------|
| **Name** | 3–255 characters | From `lumio.config.json` — edit there first |
| **Short description** | 50–200 characters | Single sentence, plain text |
| **Long description** | 100–2000 characters | Markdown supported |
| **Icon** | 512×512 px, PNG/SVG, max 1 MB | Displayed as 64×64 and 128×128 in the store |
| **Screenshots** | 1–6 images, 1280×720 px minimum, PNG/JPG | Show the extension in use on a real stream |
| **Category** | From `lumio.config.json` | `widget`, `overlay`, `bot_module`, `integration`, `theme` |

## Writing a good description

**Short description** (50–200 characters): Explain what the extension does in one sentence.

```
Display live sports scores from ESPN on your stream overlay. Supports NFL, NBA, MLB, and more.
```

**Long description**: Explain the features, use cases, and any requirements. You can use Markdown headings, lists, and bold text.

```markdown
## Features
- Live score updates every 30 seconds from the ESPN API
- Supports 10+ sports: NFL, NBA, MLB, NHL, MLS, and more
- Configurable team colors and font sizes
- Fully transparent background for seamless overlay integration

## Requirements
- An ESPN API key (free tier available at developer.espn.com)
- OBS 28+ with Browser Source plugin

## Setup
1. Add your ESPN API key in the extension secrets
2. Select your sport and league in the editor panel
3. Add the Lumio Browser Source to OBS
```

## Icon guidelines

- Use a square icon with a clear, simple design
- The icon appears at 64×64 px in search results — keep it readable at small sizes
- Use your brand colors or a relevant sports/overlay icon
- Avoid text in the icon (too small to read)

## Screenshot guidelines

- Show the extension in a real streaming setup (not just the editor panel)
- Include at least one screenshot of the layer surface on a stream
- Include one screenshot of the editor panel so users know what to expect
- Minimum resolution: 1280×720. Recommended: 1920×1080

## Updating your listing

You can update store listing content at any time without deploying a new version:

1. Open the extension dashboard
2. Navigate to **Store Listing**
3. Edit the fields and click **Save**

Name, category, and description changes take effect immediately for existing users. Icon and screenshot changes are reviewed only when they are first uploaded or significantly changed.

---

## Publishing / Review Process

# Review Process

Every extension version must pass an admin review before it can be published in the Lumio Extension Store. The review process ensures extensions are safe, functional, and appropriate for the platform.

## Version lifecycle

```
lumio deploy → draft → pending_review → in_review → testing → pending_publish → published
                                                                      ↓
                                                                  rejected
```

| Status | Description |
|--------|-------------|
| `draft` | Uploaded but not submitted. Visible only to you. |
| `pending_review` | Submitted via the submission wizard. Waiting for a reviewer. |
| `in_review` | An admin reviewer is actively checking the extension. |
| `testing` | Approved for the testing phase. Invited testers can install it. |
| `pending_publish` | Testing complete and approved. Waiting for final publish. |
| `published` | Live in the extension store. All users can find and install it. |
| `rejected` | Review failed. See the rejection reason in the dashboard. |

## What reviewers check

### Source code

- Extension source is readable and free of obfuscation
- No dynamic code execution via script injection or string-based runtime code generation with untrusted input
- No exfiltration of user data (secrets, account IDs, auth tokens) to external servers
- Server function code matches declared `egress.allowHosts` — no requests to undeclared hosts
- No infinite loops or resource exhaustion in server functions

### Permissions and egress

- Declared permissions (`"permissions"`) match what the code actually uses
- Egress allowlist hosts are appropriate for the extension's stated purpose
- No overly broad wildcards without strong justification

### Database schema

- Table names and field names are appropriate and not offensive
- No attempt to escape the extension's isolated database schema

### Extension metadata

- Name, description, icon, and screenshots are accurate and not misleading
- Category is appropriate for the extension's function
- No impersonation of other extensions or brands

### Functionality

- The extension works as described
- `Lumio.render()` is called within the 10-second timeout on all surfaces
- No visual errors or crashes on first load

## Review timeline

| Phase | Typical duration |
|-------|-----------------|
| `pending_review` → `in_review` | 1–3 business days |
| `in_review` → `testing` or `rejected` | 1–2 business days |
| `testing` | 3–14 days (you control when to request publish) |
| `pending_publish` → `published` | Within 24 hours |

First-time submissions may take longer as reviewers familiarize themselves with your extension.

## Common rejection reasons

| Reason | How to fix |
|--------|-----------|
| Undeclared egress hosts used in code | Add missing hosts to `egress.allowHosts` |
| Unused permissions declared | Remove permissions not used in `useLumioAction()` |
| Obfuscated JavaScript | Provide readable source code |
| Exfiltration of auth tokens | Never send user credentials to external servers |
| Missing or broken `Lumio.render()` | Ensure all entry files call `Lumio.render()` |
| Icon/screenshots do not match extension | Update store listing assets |
| Description is misleading | Update description to accurately reflect functionality |

## Appeal process

If your extension is rejected, you will receive the rejection reason in the dashboard and via email. You can:

1. Fix the reported issues
2. Deploy a new version with `lumio deploy`
3. Submit the new version for review

There is no separate appeal form — fix the issue and resubmit. If you believe the rejection was made in error, contact support via the dashboard with your reasoning.

## Re-review for updates

When you deploy a new version and submit it for review, only **changes** from the previous approved version are reviewed. This typically results in faster review times for minor updates.

---

## Publishing / Publishing Updates

# Publishing Updates

When you release a new version of your extension, the update behavior depends on whether the version is marked as breaking.

## Releasing a new version

```bash
# 1. Update version in lumio.config.json
# 2. Build
lumio build

# 3. Deploy (reads version from lumio.config.json)
lumio deploy -d "Fixed score display, added NHL support"

# 4. Submit via dashboard submission wizard or link printed by deploy
```

## Auto-update behavior

| Version type | Behavior for existing installations |
|-------------|-----------------------------------|
| Non-breaking (default) | Automatically updated within 24 hours of publish |
| Breaking (`--breaking` flag) | Users must manually accept the update in dashboard settings |

### Non-breaking updates

Most updates are non-breaking: bug fixes, new features, visual improvements, additional configuration options. These auto-update silently — users are notified in the dashboard but do not need to take any action.

### Breaking updates

Mark a version as breaking when:
- Storage format changes (renamed keys, restructured data)
- Server schema changes that are not backward-compatible
- UI changes that require the user to reconfigure settings
- Permissions that require new user consent

```bash
lumio deploy --breaking -v 2.0.0 -d "Storage format changed. Manual reconfiguration required after update."
```

Breaking versions show an **Update required** banner in the dashboard for affected installations. Users must click **Review and update** before the new version takes effect.

## Version pinning

Users can pin an installation to a specific version via the extension settings. Pinned installations are never auto-updated — they receive an update notification but must manually apply it.

This is useful for streamers who do not want unexpected changes mid-season.

## Semver conventions

Follow semantic versioning:

| Bump | When |
|------|------|
| `PATCH` (1.0.x) | Bug fixes, visual tweaks, no functional changes |
| `MINOR` (1.x.0) | New features, backward-compatible additions |
| `MAJOR` (x.0.0) | Breaking changes to storage, schema, or behavior |

## Update notifications

Users see update notifications in:
- The extension dashboard (**Extensions → Installed → {extension} → Updates**)
- The overlay editor sidebar (a badge on the extension name)
- A weekly email digest of pending updates (opt-in, user setting)

---

## Publishing / Visibility

# Visibility

The `visibility` field controls who can discover and install your extension.

## Visibility levels

| Level | Who can find it | Who can install it | Store listing |
|-------|----------------|---------------------|---------------|
| `private` | Only you (developer) | Only you | No |
| `unlisted` | Anyone with the direct link | Anyone with the direct link | No |
| `public` | Anyone (searchable) | Anyone | Yes |
| `paid` | Anyone (searchable) | Anyone who purchases | Yes |

## Private (default)

```json
{ "visibility": "private" }
```

Only you can see and install the extension. Use this during development and while going through the review process for the first time. Private extensions do not appear in the store and cannot be found by search.

## Unlisted

```json
{ "visibility": "unlisted" }
```

The extension is not listed in the store but can be installed by anyone with the direct URL. Useful for:
- Internal tools for your own stream team
- Beta testing with a small group
- Extensions built for a specific streamer or community

The install URL looks like:
```
https://lumio.vision/store/extensions/sports-scoreboard
```

## Public

```json
{ "visibility": "public" }
```

The extension appears in the Lumio Extension Store and can be found via search and category browsing. Available for free installation by any Lumio user. Requires a completed admin review and published status.

## Paid

```json
{ "visibility": "paid", "pricing": { "type": "one_time", "amount": 4.99, "currency": "EUR" } }
```

Appears in the store with a price tag. Requires:
- Completed [developer verification](/publishing/verification)
- Admin review and approval
- Payout method configured in dashboard

## Changing visibility

You can change visibility at any time in the extension dashboard under **Store Listing → Visibility** — no new version deployment required.

**Exceptions:**
- Changing from `private` to `public` or `paid` triggers a store listing review (first-time only)
- Changing from `public` to `private` immediately removes the extension from the store; existing installations continue working

## Private extensions always work

Private and unlisted extensions installed by their developer always work, even without going through the review process. The review process is only required for extensions published to `public` or `paid` visibility.

---

## Publishing / Monetization

# Monetization

Lumio supports two paid pricing models for extensions: one-time purchase and monthly subscription.

## Pricing models

### Free

No payment required. Anyone can install the extension.

```json
{ "pricing": { "type": "free" } }
```

### One-time purchase

Users pay once and own the extension permanently.

```json
{
  "pricing": {
    "type": "one_time",
    "amount": 4.99,
    "currency": "EUR"
  }
}
```

Minimum price: **€1.00**. Maximum: **€99.99**.

### Monthly subscription

Users pay a recurring monthly fee. If they cancel, access is revoked at the end of the billing period.

```json
{
  "pricing": {
    "type": "subscription",
    "amount": 2.99,
    "currency": "EUR",
    "interval": "monthly"
  }
}
```

Minimum price: **€0.99/month**.

## Revenue share

Lumio takes a **30% platform fee** on all transactions. Developers receive **70%** net of each payment.

| Pricing | Gross | Lumio fee (30%) | Developer receives (70%) |
|---------|-------|-----------------|--------------------------|
| One-time €4.99 | €4.99 | €1.50 | €3.49 |
| One-time €9.99 | €9.99 | €3.00 | €6.99 |
| Monthly €2.99 | €2.99/mo | €0.90/mo | €2.09/mo |

The 70% is calculated before any payment processor fees (Stripe, PayPal) which are deducted from the developer's share.

## Payout methods and minimums

| Method | Minimum payout | Processing |
|--------|---------------|------------|
| Stripe Connect | €1.00 | Automatic, within 2 business days |
| PayPal | €25.00 | Monthly batch, 5th of each month |
| SEPA bank transfer | €50.00 | Monthly batch, 5th of each month |

Unpaid balances below the minimum roll over to the next month.

## Setting up monetization

1. **Configure pricing** in `lumio.config.json` (or update via the dashboard)
2. **Complete developer verification** — required for all paid extensions
3. **Set up payout method** in the extension dashboard under **Account → Payout Settings**
4. **Submit for review** — paid extensions undergo the same review as free extensions

## Changing pricing

| Change | Impact on existing users |
|--------|--------------------------|
| Free → paid | Existing free installations remain free (grandfathered) |
| Paid → free | Access is unlocked for all; no refunds issued |
| Price increase | Existing subscribers keep their original price |
| One-time → subscription | Existing one-time purchasers retain permanent access |

## Refund policy

Lumio handles refund requests from users. Refunds are processed within 14 days of purchase for users who have not heavily used the extension. When a refund is issued, the extension is deactivated for that user and the revenue is deducted from the developer's next payout.

## Tax handling

Lumio collects and remits VAT/sales tax on transactions where required by law. The `amount` field in `lumio.config.json` is the **gross price** inclusive of applicable taxes. Your payout is the net amount after taxes and the platform fee.

---

## Publishing / Developer Verification

# Developer Verification

Developer verification is required to publish paid extensions (`one_time` or `subscription` pricing). It establishes your identity for payout purposes and ensures compliance with EU VAT and anti-money-laundering regulations.

## When verification is required

| Scenario | Verification required |
|----------|----------------------|
| Free extension, private visibility | No |
| Free extension, public visibility | No |
| Paid extension (any visibility) | Yes |

## Verification steps

Complete verification in the extension dashboard under **Account → Developer Verification**.

### Step 1: Choose account type

| Type | For |
|------|-----|
| **Individual** | Solo developers, hobbyists, freelancers |
| **Business** | Companies, studios, registered businesses |

### Step 2: Provide identity information

**Individual:**
- Legal first and last name
- Date of birth
- Country of residence
- Address

**Business:**
- Company legal name
- Company registration number
- Country of registration
- Registered address
- Representative name and date of birth (the person submitting verification)

### Step 3: Tax information

- **EU residents:** VAT ID (if registered for VAT) or personal tax ID
- **Non-EU:** Country-specific tax ID
- **US persons:** W-8BEN (non-US payees) or W-9 (US payees) — submitted via Stripe Connect

### Step 4: Set up payout method

Set up at least one payout method:

- **Stripe Connect** — connects your Stripe account for automatic payouts. Stripe's own identity verification (selfie + ID document) runs separately.
- **PayPal** — enter your PayPal email address. Payouts are batched monthly.
- **SEPA** — enter your IBAN and BIC. Payouts are batched monthly.

### Step 5: Review and submit

Review your information and submit. Verification typically completes within **1–3 business days**. You'll receive an email when it's approved or if additional information is needed.

## Status

| Status | Description |
|--------|-------------|
| `not_started` | Verification not yet initiated |
| `pending` | Submitted, awaiting review |
| `approved` | Verified — you can publish paid extensions |
| `rejected` | Additional information needed — see dashboard for details |
| `suspended` | Account suspended — contact support |

## Maintaining verification

Once approved, verification is ongoing. Lumio may request updated information annually or if:
- You change your payout method
- Regulatory requirements change
- Unusual transaction patterns are detected

---

## Publishing / Testing Phase

# Testing Phase

After an admin approves your extension for testing, it enters the `testing` status. During this phase, you can invite up to 5 testers (Free plan) or 20 testers (Pro plan) to install and use the extension before it is published publicly.

## How testing works

1. Admin approves the extension → status changes to `testing`
2. You invite testers by Lumio username
3. Testers install the extension and use it in real streaming setups
4. Testers submit feedback via the dashboard
5. When you're satisfied, you request publication

## Inviting testers

In the extension dashboard under **Versions → {version} → Testing**:

1. Click **Add tester**
2. Enter the tester's Lumio username
3. Click **Invite**

The tester receives a notification and can install the extension from a private link:

```
https://lumio.vision/store/extensions/sports-scoreboard?testing=true
```

## Tester limits

| Plan | Max testers per version |
|------|------------------------|
| Free | 5 |
| Pro | 20 |

## Tester feedback

Testers can submit feedback in the dashboard on the extension's testing page. Feedback is visible to the developer and the reviewing admin.

**Feedback categories:**
- Bug report (extension crashes, incorrect behavior)
- Visual issue (layout broken, text cut off)
- Feature request
- General comment

## Testing badge

Extensions in the testing phase show a **"Beta"** badge in the store if they are unlisted — so testers who find the link know the extension is not yet fully released.

## Requesting publication

When testing is complete and you're ready to publish:

1. Open **Versions → {version} → Testing**
2. Click **Request publication**
3. The status changes to `pending_publish`
4. An admin performs a final check and publishes the extension

Publication typically happens within 24 hours of the request.

## Abandoning a testing version

If you discover a significant bug during testing, you can deploy a new version and submit it for review without publishing the current testing version. The current testing version remains in `testing` status until you explicitly abandon it or publish it.

## CLI: checking testing status

```bash
lumio status
# Status: testing
# Testers: 3 active
# Feedback: 2 messages
```

---

## Publishing / Submission Wizard

# Submission Wizard

After deploying a new version with `lumio deploy`, you submit it for review via the **submission wizard** in the extension dashboard.

## Opening the wizard

The wizard URL is printed by `lumio deploy`:

```
Submit for review:
  https://lumio.vision/dashboard/extensions/88b2478a.../versions/1.2.0/submit
```

Or navigate to it manually: **Dashboard → Extensions → {extension} → Versions → {version} → Submit for review**

## Wizard steps

### Step 1: Basic information

Review and update the store listing for this version:

- **Extension name** (read from `lumio.config.json`, editable here for display)
- **Short description** (50–200 characters)
- **Long description** (Markdown, up to 2000 characters)
- **Category** (read from `lumio.config.json`)

### Step 2: Version and changelog

Enter the release notes for this specific version:

- **What changed** — describe new features, bug fixes, and improvements
- **Breaking changes** — if you deployed with `--breaking`, explain what changed and what users need to do

If your project has a `CHANGELOG.md` with an entry for this version, it is pre-filled automatically.

```markdown
### 1.2.0

**New features:**
- Added NHL scoreboard support
- Added team color theming

**Bug fixes:**
- Fixed score display not updating when overtime starts
- Fixed layer rendering at 4K canvas sizes
```

### Step 3: Pricing and visibility

- **Visibility** — `private`, `unlisted`, `public`, or `paid`
- **Pricing** — shown if visibility is `paid`; reads from `lumio.config.json`
- **Payout setup reminder** — shown if pricing is paid and no payout method is configured

### Step 4: Permissions review

A summary of all permissions and egress hosts your extension declared. Confirm that:
- All listed permissions are actually used
- All listed egress hosts are appropriate
- Users will understand why these permissions are needed

### Step 5: Review and submit

Final summary before submission:

- Extension name and version
- Targets (editor, layer, interactive)
- Server functions enabled (yes/no)
- Permissions list
- Egress allowlist
- Pricing

Click **Submit for review** to change status from `draft` to `pending_review`.

## After submission

- You receive an email confirmation that the extension is in the review queue
- Status updates (in_review, testing, rejected, published) trigger additional email notifications
- Check `lumio status` to poll current status
- Visit the dashboard to see reviewer notes if your extension is rejected

## Resubmitting after rejection

1. Fix the reported issues in your extension code
2. Run `lumio build && lumio deploy`
3. Open the new version's submission wizard
4. Note the changes you made to address the rejection in the changelog step
5. Submit for review

You do not need to re-enter all wizard fields from scratch — they are pre-filled from the previous submission.

---

## Teams / Teams Overview

# Teams

Developer teams let multiple people collaborate on extensions under a shared identity. A team has its own name, slug, avatar, and store presence -- extensions published by a team are attributed to the team, not individual members.

## Creating a team

There are two ways to create a team:

1. **During the developer application** -- choose "Team" as your developer type in Step 1 of the [application wizard](/getting-started/becoming-a-developer). A team is created automatically when your application is approved.
2. **From the Teams list** -- navigate to **Dashboard > Extensions > Teams** and click **Create Team**. Enter a team name and the team is created immediately with you as the owner.

When a team is created, three [default roles](/teams/roles-and-permissions) are seeded automatically: Owner, Admin, and Member.

## Multi-team support

A developer can belong to multiple teams simultaneously. The **Teams** page lists all teams you are a member of. Click any team card to open that team's dashboard, where you can manage extensions, members, roles, and settings.

There is no limit on the number of teams a developer can create or join.

## Team settings

Team owners can edit team settings from **Dashboard > Extensions > Teams > {team} > Settings**:

| Setting | Description |
|---------|-------------|
| **Team Name** | Display name shown on the Extension Store and in the dashboard |
| **Slug** | URL-safe identifier, set at creation time (read-only after creation) |

### Deleting a team

Team owners can delete a team from the **Danger Zone** section on the settings page. Deletion is permanent and removes the team, its roles, and all member associations. Extensions owned by the team must be transferred or removed before deletion.

## Team members

Navigate to **Dashboard > Extensions > Teams > {team} > Members** to view and manage members.

### Inviting members

Team members with the `team-members:invite` permission can create invite links:

1. Click **Invite Member**
2. Choose a role to assign to the invitee
3. Optionally restrict the invite to a specific email address
4. Set the maximum number of uses and expiration time (default: 1 use, 7 days)
5. Share the generated invite link

The invitee opens the link, logs in to Lumio, and accepts the invitation. They are added to the team with the selected role.

### Changing a member's role

Members with the `team-members:edit` permission can reassign roles for existing members. Navigate to the member list, click a member, and select a new role.

### Removing members

Members with the `team-members:remove` permission can remove other members from the team. The team owner cannot be removed.

## Next steps

- [Roles and Permissions](/teams/roles-and-permissions) -- configure what each team member can do
- [Security & API Keys](/account/security) -- manage team credentials
- [Payout Settings](/account/payout-settings) -- configure revenue sharing

---

## Teams / Roles & Permissions

# Team Roles & Permissions

Teams use a full RBAC (role-based access control) system. Every team member is assigned a role, and each role grants a specific set of permissions that control what the member can do within the team.

## Default roles

Every new team is created with three roles:

| Role | Type | Permissions | Description |
|------|------|-------------|-------------|
| **Owner** | System (cannot be deleted) | All 20 | Full team access. Assigned to the team creator. |
| **Admin** | Default | 17 | Manage extensions and team members. Cannot edit team settings, manage payouts, or remove members. |
| **Member** | Default | 7 | View and develop extensions. Read-only access to members, secrets, and settings. |

## Permission reference

There are 20 permissions across 7 categories:

### Extensions

| Permission | Key | Owner | Admin | Member |
|-----------|-----|:-----:|:-----:|:------:|
| Create extensions | `team-extensions:create` | Yes | Yes | Yes |
| Edit extensions | `team-extensions:edit` | Yes | Yes | Yes |
| Delete extensions | `team-extensions:delete` | Yes | Yes | -- |
| Publish extensions | `team-extensions:publish` | Yes | Yes | -- |
| View analytics | `team-extensions:analytics` | Yes | Yes | Yes |

### Versions

| Permission | Key | Owner | Admin | Member |
|-----------|-----|:-----:|:-----:|:------:|
| Create versions | `team-versions:create` | Yes | Yes | Yes |
| Edit versions | `team-versions:edit` | Yes | Yes | -- |

### Secrets

| Permission | Key | Owner | Admin | Member |
|-----------|-----|:-----:|:-----:|:------:|
| Read secrets | `team-secrets:read` | Yes | Yes | Yes |
| Edit secrets | `team-secrets:edit` | Yes | Yes | -- |

### Testers

| Permission | Key | Owner | Admin | Member |
|-----------|-----|:-----:|:-----:|:------:|
| Read testers | `team-testers:read` | Yes | Yes | -- |
| Invite testers | `team-testers:invite` | Yes | Yes | -- |
| Remove testers | `team-testers:remove` | Yes | Yes | -- |

### Members

| Permission | Key | Owner | Admin | Member |
|-----------|-----|:-----:|:-----:|:------:|
| Read member list | `team-members:read` | Yes | Yes | Yes |
| Invite members | `team-members:invite` | Yes | Yes | -- |
| Edit member roles | `team-members:edit` | Yes | Yes | -- |
| Remove members | `team-members:remove` | Yes | -- | -- |

### Settings

| Permission | Key | Owner | Admin | Member |
|-----------|-----|:-----:|:-----:|:------:|
| Read settings | `team-settings:read` | Yes | Yes | Yes |
| Edit settings | `team-settings:edit` | Yes | -- | -- |

### Payouts

| Permission | Key | Owner | Admin | Member |
|-----------|-----|:-----:|:-----:|:------:|
| Read payout info | `team-payouts:read` | Yes | Yes | -- |
| Edit payout config | `team-payouts:edit` | Yes | -- | -- |

## Creating custom roles

In addition to the three default roles, team owners and members with `team-settings:edit` permission can create custom roles:

1. Navigate to **Dashboard > Extensions > Teams > {team} > Roles**
2. Click **Create Role**
3. Enter a name and optional description
4. Choose a color for the role badge
5. Select the permissions to grant
6. Save the role

Custom roles appear in the role list and can be assigned to team members via the members page or when creating invite links.

### Editing a custom role

Click a custom role from the roles list to edit its name, description, color, or permissions. Changes take effect immediately for all members assigned to that role.

### Deleting a custom role

Custom roles (where `is_system` is false) can be deleted. Members assigned to a deleted role are reassigned to the default **Member** role. The system **Owner** role cannot be deleted or modified.

## Permission enforcement

Permissions are enforced at the API level. Both the GraphQL and REST APIs check team permissions before executing any team-scoped operation. If a member lacks the required permission, the request is rejected with an authorization error.

The dashboard UI also respects permissions -- buttons and menu items for actions the current user cannot perform are hidden or disabled.

## Next steps

- [Teams Overview](/teams/overview) -- team creation and management
- [Security & API Keys](/account/security) -- manage API keys and 2FA

---

## Automation Nodes / Automation Nodes Overview

# Automation Nodes

Automation nodes are extensions that add custom functionality to the visual Automation Builder. Users drag your node onto the canvas, configure it, and connect it to other nodes to build automated workflows.

Three node types are supported:

| Type | Purpose | Example |
|------|---------|---------|
| **Trigger** | Start an automation from an external event | Shopify order webhook, RSS feed poll |
| **Action** | Perform work when the automation runs | Send a Discord message, update a spreadsheet |
| **Logic** | Branch the flow based on a condition | Check if order total exceeds a threshold |

Each automation node extension declares exactly one node. Multiple nodes require multiple extensions.

## Architecture

Automation nodes run server-side in a V8 isolate inside the Automation Worker service. The execution flow:

1. The Automation Builder stores the node graph (nodes + edges) in the database
2. When a trigger fires (webhook, poll, or manual), the Automation Engine walks the graph
3. For each extension node, the Engine dispatches to the Automation Worker via HTTP
4. The Worker executes your handler in a sandboxed V8 isolate
5. The handler result flows back: action output feeds downstream nodes, logic branches route the flow

The node config UI in the Automation Builder is rendered as a Custom React Component via the SDK iframe sandbox (same mechanism as widget config panels).

## Manifest

Automation node extensions use `category: "automation_node"` and require a `node_type` field plus a `node` configuration object:

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "your-uuid-here",
  "name": "My Custom Action",
  "category": "automation_node",
  "version": "1.0.0",
  "node_type": "action",
  "node": {
    "input_schema": {
      "type": "object",
      "properties": {
        "message": { "type": "string", "title": "Message" }
      },
      "required": ["message"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "success": { "type": "boolean" }
      }
    },
    "icon": "send",
    "color": "#3b82f6"
  },
  "targets": ["editor"],
  "server": true,
  "egress": {
    "allow_hosts": ["api.example.com"]
  }
}
```

Key manifest rules:

- `category` must be `"automation_node"`
- `node_type` must be `"trigger"`, `"action"`, or `"logic"`
- `targets` must include `"editor"` (the automation builder surface)
- `server` must be `true` (nodes execute server-side)
- Trigger nodes require `node.trigger_mode` (`"webhook"`, `"polling"`, or `"both"`)
- Action and logic nodes must NOT have `trigger_mode` or `poll_interval_seconds`

## Handler file

Your server handler lives in `server/handler.ts`. Each node type uses a different SDK wrapper:

- **Action:** `defineAutomationAction`
- **Trigger:** `defineAutomationTrigger`
- **Logic:** `defineAutomationLogic`

See the dedicated guide for each node type:

- [Action Nodes](/automation-nodes/action-nodes)
- [Trigger Nodes](/automation-nodes/trigger-nodes)
- [Logic Nodes](/automation-nodes/logic-nodes)

## Context API

Every handler receives a `ctx` object:

| Property | Type | Description |
|----------|------|-------------|
| `ctx.fetch(url, options)` | Function | HTTP client with egress allowlist enforcement |
| `ctx.cache.get(key)` | Function | Read from scoped Redis cache |
| `ctx.cache.set(key, value, ttl?)` | Function | Write to scoped Redis cache |
| `ctx.installConfig` | `Record<string, unknown>` | Extension-level config (from `extension_installs.config`) |
| `ctx.nodeConfig` | `Record<string, unknown>` | Per-node-instance config (from `automation_nodes.config`) |
| `ctx.inputData` | `Record<string, unknown>` | Data from upstream node or webhook/poll payload |
| `ctx.auth` | Object | `{ accountId, extensionId, installId }` |

## Timeouts

| Node Type | Timeout | Rationale |
|-----------|---------|-----------|
| Action | 5000ms | May call external APIs |
| Logic | 2000ms | Should be fast computation |
| Trigger (poll) | 5000ms | May check external service |
| Trigger (webhook) | 1000ms | Just parsing/validation |

## Next steps

- [Action Nodes](/automation-nodes/action-nodes) -- build an action node
- [Trigger Nodes](/automation-nodes/trigger-nodes) -- build a trigger node
- [Logic Nodes](/automation-nodes/logic-nodes) -- build a logic node
- [Config Panel](/automation-nodes/config-panel) -- custom config UI in the Automation Builder
- [Testing](/automation-nodes/testing) -- local development and testing

---

## Automation Nodes / Action Nodes

# Action Nodes

Action nodes perform work: call an external API, transform data, send a message, or write to a database. They receive input data from the upstream node and produce output data for downstream nodes.

## Create a project

```bash
lumio init my-action-node
```

When prompted:
- **Category:** `automation_node`
- **Node type:** Action

## Handler

Define your action handler in `server/handler.ts`:

```typescript
import { defineAutomationAction } from "@zaflun/lumio-sdk/server";

defineAutomationAction(async (ctx) => {
  const response = await ctx.fetch("https://api.example.com/data", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ query: ctx.nodeConfig.query }),
  });
  const data = await response.json();

  return {
    output: { result: data.result, count: data.items.length },
    status: "success",
  };
});
```

## Return value

The handler must return an `ActionResult`:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `output` | `Record<string, unknown>` | Yes | Data for downstream nodes. Must match the `output_schema` from the manifest. |
| `status` | `"success" \| "error"` | Yes | Whether the action completed successfully |
| `error_message` | `string` | No | Human-readable error message (only when `status: "error"`) |

When `status` is `"error"`, the automation engine stops the current execution branch and records the error in the execution history.

## Input/output schemas

The manifest declares what data the node accepts and produces:

```json
{
  "node": {
    "input_schema": {
      "type": "object",
      "properties": {
        "message": { "type": "string", "title": "Message to send" },
        "channel": { "type": "string", "title": "Channel name" }
      },
      "required": ["message"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "message_id": { "type": "string" },
        "sent_at": { "type": "string" }
      }
    }
  }
}
```

The `input_schema` drives the auto-generated fallback config UI when no custom editor surface is provided. The `output_schema` defines which fields downstream nodes can reference via template syntax (`{{ext_abc12.message_id}}`).

## Output template references

Downstream nodes reference your action output using template syntax:

```
{{ext_abc12.message_id}}
{{ext_abc12.sent_at}}
```

Format: `ext_{short_id}.{output_field}`. Fields are derived from the `output_schema` properties.

## Example: Send a Discord webhook

```typescript
import { defineAutomationAction } from "@zaflun/lumio-sdk/server";

defineAutomationAction(async (ctx) => {
  const webhookUrl = ctx.installConfig.discord_webhook_url;
  const message = ctx.inputData.message ?? ctx.nodeConfig.default_message;

  const res = await ctx.fetch(webhookUrl, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ content: message }),
  });

  if (!res.ok) {
    return {
      output: {},
      status: "error",
      error_message: `Discord webhook failed: ${res.status}`,
    };
  }

  return {
    output: { sent: true, status_code: res.status },
    status: "success",
  };
});
```

## Next steps

- [Config Panel](/automation-nodes/config-panel) -- build a custom config UI
- [Testing](/automation-nodes/testing) -- test your action node locally

---

## Automation Nodes / Trigger Nodes

# Trigger Nodes

Trigger nodes are entry points for automations. They fire when an external event occurs (webhook) or when a periodic check finds new data (polling).

## Trigger modes

| Mode | Description | Use case |
|------|-------------|----------|
| `webhook` | External service sends HTTP POST to a generated URL | Shopify orders, GitHub events, Stripe payments |
| `polling` | Worker periodically calls your handler to check for events | RSS feeds, API endpoints without webhooks |
| `both` | Support both webhook and polling | Services that offer webhooks but need a fallback |

## Create a project

```bash
lumio init my-trigger
```

When prompted:
- **Category:** `automation_node`
- **Node type:** Trigger
- **Trigger mode:** Choose webhook, polling, or both

## Handler

Trigger handlers use `defineAutomationTrigger` with `onWebhook` and/or `onPoll` methods:

```typescript
import { defineAutomationTrigger } from "@zaflun/lumio-sdk/server";

defineAutomationTrigger({
  onWebhook: async (ctx) => {
    const payload = ctx.webhookBody;
    if (payload.event !== "order.created") {
      return { fired: false };
    }
    return {
      fired: true,
      output: {
        order_id: payload.id,
        customer_name: payload.customer.name,
        total: payload.total_price,
        currency: payload.currency,
      },
    };
  },
  onPoll: async (ctx) => {
    const lastCheck = await ctx.cache.get("last_check_ts");
    const res = await ctx.fetch(
      `https://api.example.com/events?since=${lastCheck}`
    );
    const events = await res.json();

    if (events.length === 0) return null;

    await ctx.cache.set("last_check_ts", Date.now().toString());
    return {
      fired: true,
      output: events[0],
    };
  },
});
```

## Return value

Both `onWebhook` and `onPoll` return a `TriggerResult` (or `null`):

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `fired` | `boolean` | Yes | Whether the trigger should start the automation |
| `output` | `Record<string, unknown>` | Only when `fired: true` | Event data. Must match the `output_schema` from the manifest. |

Returning `null` or `{ fired: false }` silently ignores the event. No automation runs.

## Webhook flow

When a user **saves** an automation that contains your webhook trigger node
(`trigger_mode` `webhook` or `both`):

1. Lumio registers the trigger and generates a unique webhook URL plus a
   random URL-safe secret. The secret is minted **once** and preserved across
   later edits — re-saving the automation never rotates it, so a URL already
   configured in an external service keeps working. Removing the trigger node
   disables its registration (the secret is restored if the node is re-added).
2. The user reads the URL + secret from the Automation Builder (backed by the
   `automationWebhookUrl` GraphQL query / `GET /v1/automation/webhooks/{install_id}/{automation_id}`)
   and configures the external service with them.
3. External service sends `POST /v1/automation/webhooks/{extension_id}/{install_id}` with `X-Webhook-Secret` header
4. The API validates the secret (constant-time) and forwards to the Automation Worker
5. Your `onWebhook` handler runs in V8
6. If `fired: true`, the automation engine runs the full flow

The webhook URL is displayed in the Automation Builder when the user selects a webhook trigger node.

## Polling flow

For polling triggers, the Automation Worker runs your `onPoll` handler at the configured interval:

1. User enables the automation
2. The Worker starts a poll loop at `poll_interval_seconds` (10-300, default 30)
3. Each iteration calls your `onPoll` handler
4. If `fired: true`, the automation engine runs the full flow
5. On disable, the poll loop stops

Use `ctx.cache` to track the last-checked timestamp and avoid re-processing events.

## Manifest configuration

```json
{
  "node_type": "trigger",
  "node": {
    "trigger_mode": "webhook",
    "poll_interval_seconds": null,
    "input_schema": {
      "type": "object",
      "properties": {
        "shop_domain": { "type": "string", "title": "Shop Domain" }
      },
      "required": ["shop_domain"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string" },
        "customer_name": { "type": "string" },
        "total": { "type": "number" },
        "currency": { "type": "string" }
      }
    }
  }
}
```

For polling triggers, set `poll_interval_seconds` to a value between 10 and 300.

## Next steps

- [Config Panel](/automation-nodes/config-panel) -- build a custom config UI
- [Testing](/automation-nodes/testing) -- simulate webhooks and polls locally

---

## Automation Nodes / Logic Nodes

# Logic Nodes

Logic nodes evaluate conditions and route the automation flow to different branches. Each branch corresponds to an output handle on the node.

## Create a project

```bash
lumio init my-logic-node
```

When prompted:
- **Category:** `automation_node`
- **Node type:** Logic

## Handler

Logic handlers use `defineAutomationLogic` and return a branch key:

```typescript
import { defineAutomationLogic } from "@zaflun/lumio-sdk/server";

defineAutomationLogic(async (ctx) => {
  const value = ctx.inputData.amount;
  if (value > ctx.nodeConfig.threshold) {
    return "above";
  }
  return "below";
});
```

## Return value

The handler returns a `string` -- the branch key. This string must match one of the output handle keys defined in the Automation Builder.

Common patterns:

| Pattern | Branch keys | Use case |
|---------|-------------|----------|
| Boolean | `"true"`, `"false"` | Simple yes/no condition |
| Threshold | `"above"`, `"below"` | Numeric comparison |
| Match | `"match"`, `"no_match"` | Pattern matching |
| Category | `"category_a"`, `"category_b"`, `"other"` | Multi-way routing |

The Automation Builder displays output handles for each unique branch key that the node can return. Users connect edges from these handles to downstream nodes.

## Input data

Logic nodes receive data from the upstream node via `ctx.inputData`. The `input_schema` in the manifest defines expected fields:

```json
{
  "node_type": "logic",
  "node": {
    "input_schema": {
      "type": "object",
      "properties": {
        "amount": { "type": "number", "title": "Amount to check" }
      },
      "required": ["amount"]
    },
    "output_schema": {
      "type": "object",
      "properties": {}
    }
  }
}
```

Logic nodes typically have an empty `output_schema` since they route rather than transform data. The upstream data passes through unchanged to the selected branch.

## Example: Time-of-day router

```typescript
import { defineAutomationLogic } from "@zaflun/lumio-sdk/server";

defineAutomationLogic(async (ctx) => {
  const hour = new Date().getUTCHours();
  const offset = Number(ctx.nodeConfig.utc_offset ?? 0);
  const localHour = (hour + offset + 24) % 24;

  if (localHour >= 6 && localHour < 12) return "morning";
  if (localHour >= 12 && localHour < 18) return "afternoon";
  if (localHour >= 18 && localHour < 22) return "evening";
  return "night";
});
```

## Timeout

Logic nodes have a 2000ms timeout. Keep logic simple and avoid external API calls. If you need to fetch data, use an action node upstream and pass the result to the logic node.

## Next steps

- [Config Panel](/automation-nodes/config-panel) -- build a custom config UI
- [Testing](/automation-nodes/testing) -- test branching logic locally

---

## Automation Nodes / Config Panel

# Config Panel

When a user selects your node on the Automation Builder canvas, the config panel appears. You can build a custom React config panel using the SDK iframe sandbox, or rely on the auto-generated fallback UI derived from `input_schema`.

## SDK iframe mechanism

The config panel uses the same iframe sandwich as widget editor panels:

```
Automation Builder (host) -> Supervisor iframe -> Extension Runtime iframe -> Your editor.tsx
```

Your extension must include `"editor"` in its `targets` array. The editor entry point renders your config panel component.

## Using useLumioConfig

The `useLumioConfig` hook reads and writes the per-node-instance config (`automation_nodes.config`):

```typescript
import { Lumio, CompactView } from "@zaflun/lumio-sdk";
import { useLumioConfig } from "@zaflun/lumio-sdk/hooks";

function ConfigPanel() {
  const [config, setConfig] = useLumioConfig();

  return (
    <CompactView title="Threshold Settings">
      <label>
        Threshold:
        <input
          type="number"
          value={config.threshold ?? 50}
          onChange={(e) => setConfig({
            ...config,
            threshold: Number(e.target.value),
          })}
        />
      </label>
      <label>
        Comparison:
        <select
          value={config.comparison ?? "greater_than"}
          onChange={(e) => setConfig({
            ...config,
            comparison: e.target.value,
          })}
        >
          <option value="greater_than">Greater than</option>
          <option value="less_than">Less than</option>
          <option value="equal">Equal to</option>
        </select>
      </label>
    </CompactView>
  );
}

Lumio.render(<ConfigPanel />, { target: "editor" });
```

Changes sync back to `automation_nodes.config` via the parent host communication protocol.

## Fallback UI

If your extension does not include an editor surface, the Automation Builder renders an auto-generated form based on `node.input_schema`. Each property in the schema becomes a form field:

| Schema type | UI element |
|-------------|-----------|
| `string` | Text input |
| `number` | Number input |
| `boolean` | Checkbox |
| `string` with `enum` | Select dropdown |

This fallback is sufficient for simple configurations. Use a custom editor surface when you need richer controls (color pickers, multi-step wizards, visual selectors).

## Next steps

- [Testing](/automation-nodes/testing) -- test the config panel locally
- [SDK Hooks Reference](/sdk/hooks/use-lumio-config) -- full `useLumioConfig` API

---

## Automation Nodes / Testing

# Testing Automation Nodes

The Lumio CLI provides a local dev server for testing automation nodes without deploying.

## Start the dev server

```bash
lumio dev --automation-node
```

Output:

```
Automation Node Dev Server
Extension: My Custom Action
Node type: action

Commands:
  /execute [json]     - Execute the node with input data
  /webhook [json]     - Simulate a webhook POST payload
  /poll               - Trigger a poll cycle
  /config [json]      - Set node instance config
  /install-config [j] - Set extension install config
  /quit               - Exit

>
```

The dev server automatically detects `category: "automation_node"` in `lumio.config.json` and launches the appropriate simulator.

## Testing action nodes

Use `/execute` to invoke the action handler with input data:

```
> /config {"query": "latest posts"}
  Node config updated.

> /execute {"message": "Hello from automation"}
  [action] Executing with input: {"message":"Hello from automation"}
  [action] Result: { output: { result: "Processed: Hello from automation" }, status: "success" }
  [action] Completed in 12ms
```

## Testing trigger nodes

### Webhook triggers

Simulate a webhook payload with `/webhook`:

```
> /webhook {"event": "order.created", "id": "12345", "customer": {"name": "Alice"}, "total_price": 59.99, "currency": "USD"}
  [trigger:webhook] Received payload: {"event":"order.created",...}
  [trigger:webhook] Result: { fired: true, output: { order_id: "12345", customer_name: "Alice", total: 59.99, currency: "USD" } }
```

### Polling triggers

Trigger a poll cycle with `/poll`:

```
> /poll
  [trigger:poll] Polling...
  [trigger:poll] Result: { fired: false }

> /poll
  [trigger:poll] Polling...
  [trigger:poll] Result: { fired: true, output: { ... } }
```

## Testing logic nodes

Use `/execute` to test branching:

```
> /config {"threshold": 100}
  Node config updated.

> /execute {"amount": 150}
  [logic] Executing with input: {"amount":150}
  [logic] Branch: "above"

> /execute {"amount": 50}
  [logic] Executing with input: {"amount":50}
  [logic] Branch: "below"
```

## Setting config

Set the per-node config to test different configurations:

```
> /config {"threshold": 100, "comparison": "greater_than"}
  Node config updated.
```

Set the extension install config to test install-level settings:

```
> /install-config {"api_key": "test-key-123"}
  Install config updated.
```

## Hot-reload

The dev server watches `server/handler.ts` for changes and reloads automatically:

```
[hot-reload] Detected change in server/handler.ts
[hot-reload] Handler reloaded
```

## Deploy

Build and deploy like any other extension:

```bash
lumio deploy
```

After deployment, the automation node appears in the Automation Builder toolbar under the "Extensions" section.

## Next steps

- [Overview](/automation-nodes/overview) -- automation node architecture
- [Debugging](/guides/debugging) -- general extension debugging

---

## Account / Extension ID & Namespace

# Extension ID & Namespace

Every extension published on Lumio has a globally unique identifier and a namespace that forms the root of all storage keys, permission scopes, and API routes belonging to it.

## Extension ID

The extension ID is assigned at creation time and never changes. It looks like a UUID:

```
ext_01j9k2m3n4p5q6r7s8t9u0v1w2
```

You can find it in `lumio.config.json` under the `extensionId` field and in the extension dashboard under **Extension → Settings → Extension ID**.

```json
{
  "extensionId": "ext_01j9k2m3n4p5q6r7s8t9u0v1w2",
  "name": "My Scoreboard"
}
```

The extension ID is used:

- As the primary key for extension installs, versions, and reviews
- In the Lumio Developer API to query extension metadata
- In support requests when contacting Lumio

## Slug

In addition to the extension ID, each extension has a human-readable **slug** used in the store URL:

```
https://lumio.vision/store/extensions/my-scoreboard
```

The slug is derived from the extension name at creation time and must be globally unique across the store. Slugs:

- Are lowercase, URL-safe (letters, digits, and hyphens only)
- May be changed once before the first public release via the dashboard
- Cannot be changed after the extension has been publicly listed

## Namespace

The extension namespace is derived from the extension ID and scopes all server-side storage. Storage keys in server functions are automatically prefixed with the namespace — you cannot access or overwrite another extension's data.

```typescript
// Internal key: ext_01j9k2.../user/u_abc123/score
await ctx.db.get("user", userId, "score");
```

The namespace also applies to:

- **Redis pub/sub channels** — real-time messages are isolated per extension
- **Secret keys** — secrets set via `lumio secrets set` are namespaced automatically
- **Egress quotas** — rate limits are tracked per extension

## Transferring ownership

Extensions are owned by the developer account that created them. Ownership can be transferred to another verified developer account via **Extension → Settings → Transfer Ownership**.

After transfer:

- The extension ID and slug remain unchanged
- The previous owner loses access immediately
- Revenue from in-flight transactions routes to the new owner's payout method
- Version history, reviews, and install base are preserved

Ownership transfer is irreversible. Both parties receive an email confirmation.

## Deleting an extension

Extensions can be deleted from the dashboard if they have never been publicly listed. Once listed, deletion requires contacting Lumio support. Deleted extensions:

- Are removed from the store immediately
- Existing installs continue to function until the associated overlay is removed
- Server function logs are retained for 30 days then purged
- Extension ID and slug are permanently reserved and cannot be reused

---

## Account / Limits & Quotas

# Limits & Quotas

Lumio enforces per-account and per-extension limits to ensure fair resource usage across the platform. This page lists the defaults and the process for requesting an increase.

## Per-account limits

| Resource | Default limit | Notes |
|----------|--------------|-------|
| Extensions per account | 25 | Across all visibility levels |
| Versions per extension | 100 | Oldest versions are archived after 100 |
| Team members | 10 | Includes owner |
| API keys | 20 | Active keys; revoked keys do not count |
| Secret keys per extension | 20 | Stored in Lumio Vault |

## Per-extension storage limits

| Resource | Default limit | Notes |
|----------|--------------|-------|
| Global storage | 100 MB | Shared across all installs |
| Per-install storage | 10 MB | Per unique `installId` |
| Key count (global) | 10,000 keys | |
| Key count (per install) | 1,000 keys | |
| Value size | 64 KB | Per key |
| Key name length | 255 bytes | UTF-8 |

## Server function limits

| Resource | Default limit | Notes |
|----------|--------------|-------|
| Actions per extension | 50 | Total defined actions |
| Invocations per minute | 300 | Across all users of this extension |
| Invocation timeout | 30 seconds | Applies to `handler` execution |
| External fetch calls per invocation | 10 | Via `ctx.fetch()` |
| Response payload size | 1 MB | Returned from an action |
| Egress hosts | 20 | Entries in `allowHosts` |

## Real-time limits

| Resource | Default limit | Notes |
|----------|--------------|-------|
| Active WebSocket connections per install | 5 | Overlay + popout windows |
| Pub/sub messages per second (push) | 100 | Via `ctx.realtime.push()` |
| Message payload size | 64 KB | Per pub/sub message |

## Bundled sound limits

| Resource | Default limit | Notes |
|----------|--------------|-------|
| Sounds per extension manifest | 200 | Maximum entries in `sounds` array |
| Resolved sound limit | 50 | Per-extension deploy cap (see below) |
| Sound file size | 10 MB | Per individual sound file |
| Sound file warning | 5 MB | CLI warns above this threshold |
| Total bundle size | 50 MB | All files combined per deploy |

The resolved sound limit follows a 3-tier priority chain:

1. **Per-extension override** — admin-set via `extensions.max_sounds` column
2. **Per-developer override** — admin-set via developer limit overrides (`max_sounds_per_extension` key)
3. **Platform default** — 50

The CLI checks this limit before deploying (`GET /v1/developer/extensions/{id}/limits`). The server validates again at upload and install time.

Supported audio formats: MP3, WAV, OGG, WebM, M4A, AAC, FLAC.

To request a limit increase, visit the **Developer Limits** page at `/account/developer/limits`. Select the scope (team/developer default or a specific extension), choose which limits to increase, enter your desired values with a reason, and submit. An admin reviews and approves or rejects the request. You can track request status on the same page under the **Requests** tab.

## Build limits

| Resource | Default limit | Notes |
|----------|--------------|-------|
| Compiled bundle size (layer) | 5 MB | Gzipped |
| Compiled bundle size (editor) | 5 MB | Gzipped |
| Compiled bundle size (interactive) | 5 MB | Gzipped |
| Static assets (images, fonts) | 20 MB | Per extension version |
| Build time | 5 minutes | Per `lumio deploy` run |

## Rate limits on the Developer API

| Endpoint | Limit |
|----------|-------|
| `GET` endpoints | 120 requests/minute |
| `POST /extensions` | 10 requests/hour |
| `POST /extensions/:id/versions` | 30 requests/hour |
| `DELETE` endpoints | 30 requests/minute |

Limits are applied per authenticated developer account. Exceeding a limit returns HTTP `429 Too Many Requests` with a `Retry-After` header.

## Requesting a limit increase

To request a limit increase, visit the **Developer Limits** page at `/account/developer/limits`:

1. Click **Request increase** next to a configurable limit
2. Select the scope: **Team / Developer account** (applies to all extensions) or a **Specific extension**
3. Check the limits you want to increase and enter your desired values
4. Provide a reason (minimum 20 characters) explaining your use case
5. Review the summary and submit

Requests are reviewed by Lumio admins. Approved increases apply immediately. You can track request status on the same page under the **Requests** tab. Increases for storage, invocation rate, and bundle size are granted on a case-by-case basis and may require a Pro or Enterprise plan.

## Hard limits

The following limits cannot be increased regardless of plan:

| Resource | Hard limit |
|----------|-----------|
| Value size | 1 MB |
| Action invocation timeout | 120 seconds |
| Response payload | 10 MB |
| Egress request timeout | 30 seconds |
| Versions per extension | 500 |

---

## Account / Security & API Keys

# Security & API Keys

Your Lumio account uses user API keys for programmatic access — to the CLI, CI/CD pipelines, and the Developer REST API. This page explains how keys work and best practices for keeping them secure.

## API keys

User API keys are personal credentials scoped to your active account. They are used by:

- The `lumio` CLI (`lumio login --token <key>`)
- CI/CD pipelines running `lumio deploy`
- Direct calls to the Developer REST API

### Creating a key

1. Open [lumio.vision](https://lumio.vision)
2. Navigate to **Dashboard → API Keys**
3. Click **Create API key**
4. Enter a label (e.g. `ci-github-actions`)
5. Select the permissions the key should carry
6. Optionally set an expiry
7. Copy the key — it is shown only once

Keys are prefixed with `lm_usr_`. Lumio stores only a hash of the key, so the full secret cannot be recovered after creation.

### Key permissions

Each API key carries the permissions selected at creation time. A key can never grant more permissions than the user who creates it; the backend rejects any permission the creator does not currently hold.

### Revoking a key

Revoke a key from **Dashboard → API Keys**. Revocation hard-deletes the key, so it cannot be restored.

### Rotation recommendation

Rotate API keys every 90 days or immediately when:

- A team member with access to the key leaves
- You suspect the key may have been exposed
- You rotate secrets in your CI/CD platform

## Teams and shared access

Multiple developers can collaborate on extensions via [developer teams](/teams/overview). Each team member authenticates with their own credentials -- shared passwords or shared API keys are not needed or recommended.

Teams use a full RBAC system with 18 granular permissions across 7 categories. Three default roles (Owner, Admin, Member) are created for every team, and custom roles can be added. See [Roles & Permissions](/teams/roles-and-permissions) for the complete permission reference.

## Two-factor authentication

Enable 2FA for your account under **Account → Security → Two-Factor Authentication**. Supported methods:

- **TOTP** — any authenticator app (Google Authenticator, Authy, 1Password)
- **Passkey** — hardware security key or platform authenticator

2FA is required for all accounts that have published paid extensions. It is strongly recommended for all accounts.

## Audit log

Every authentication event, deployment, and settings change is logged in the audit log under **Account → Security → Audit Log**. Log entries include:

| Field | Description |
|-------|-------------|
| `timestamp` | UTC timestamp of the event |
| `event` | Event type (e.g. `api_key.created`, `extension.deployed`) |
| `actor` | Email or API key label |
| `ip` | Source IP address |
| `result` | `success` or `failure` |

Audit logs are retained for 90 days.

## Responsible disclosure

If you discover a security vulnerability in the Lumio platform, report it to **security@lumio.vision**. Include a description of the issue, steps to reproduce, and impact assessment. We follow a 90-day disclosure timeline and offer recognition in our security hall of fame for valid reports.

Do not report vulnerabilities via GitHub issues or the public support channel.

## Security best practices

- Store API keys in your CI/CD secret store (GitHub Actions secrets, GitLab CI variables), never in source code
- Use environment-specific keys — a separate key for staging vs production deployments
- Enable 2FA on your developer account
- Review the audit log monthly for unexpected access
- Revoke keys that are no longer in use
- Never share your API key in support tickets, Discord, or forums — Lumio staff will never ask for your key

---

## Account / Payout Settings

# Payout Settings

Payout settings control how and when Lumio transfers your revenue share to you. You must complete [developer verification](/publishing/verification) before adding a payout method.

## Payout methods

You can configure up to three payout methods. Lumio attempts the primary method first; if it fails, it falls back to the secondary method.

### Stripe Connect

Stripe Connect is the fastest payout method. It connects your existing Stripe account (or creates one) and enables automatic payouts within 2 business days of each transaction.

To connect Stripe:

1. Go to **Account → Payout Settings → Add Method → Stripe Connect**
2. You are redirected to Stripe's onboarding flow
3. Complete Stripe's identity verification (separate from Lumio's verification)
4. Return to the dashboard — your account is now linked

Stripe Connect payouts:

- **Minimum payout:** €1.00
- **Frequency:** Automatic, 2 business days after each transaction settles
- **Currencies:** EUR, USD, GBP (based on your Stripe account country)
- **Fees:** Stripe's standard processing fee (~1.4% + €0.25 for EU cards) is deducted from your share

### PayPal

PayPal payouts are batched monthly and require a verified PayPal account with the same email address as your Lumio developer account.

To connect PayPal:

1. Go to **Account → Payout Settings → Add Method → PayPal**
2. Enter your PayPal email address
3. Lumio sends a €0.01 verification payment — confirm receipt in your PayPal account

PayPal payouts:

- **Minimum payout:** €25.00 — balances below this roll over to the next month
- **Frequency:** Monthly batch, paid on the 5th of each month for the previous month's earnings
- **Currencies:** EUR
- **Fees:** PayPal's receiving fee is deducted from your payout

### SEPA Bank Transfer

SEPA transfers are available for developers with a bank account in the SEPA zone (EU + EEA + Switzerland + UK).

To configure SEPA:

1. Go to **Account → Payout Settings → Add Method → SEPA**
2. Enter your IBAN and BIC/SWIFT code
3. Enter the account holder name exactly as it appears on the bank account
4. Lumio performs a micro-deposit verification (€0.01) — confirm the amount shown in your bank statement

SEPA payouts:

- **Minimum payout:** €50.00 — balances below this roll over to the next month
- **Frequency:** Monthly batch, paid on the 5th of each month for the previous month's earnings
- **Currencies:** EUR
- **Fees:** No additional fees from Lumio; your bank may charge a receiving fee

## Revenue share

Lumio retains 30% of each transaction as a platform fee. Developers receive 70%, calculated on the gross transaction amount before payment processor fees.

| Pricing | Gross | Lumio (30%) | Your share (70%) |
|---------|-------|-------------|-----------------|
| €4.99 one-time | €4.99 | €1.50 | €3.49 |
| €9.99 one-time | €9.99 | €3.00 | €6.99 |
| €2.99/month | €2.99 | €0.90 | €2.09/month |

Payment processor fees (Stripe, PayPal) are deducted from your 70% share and depend on the buyer's payment method and country.

## Payout schedule

| Method | Settlement |
|--------|-----------|
| Stripe Connect | 2 business days after each transaction |
| PayPal | 5th of each month (monthly batch) |
| SEPA | 5th of each month (monthly batch) |

If the 5th falls on a weekend or bank holiday, the batch is processed the next business day.

## Viewing earnings

Your earnings dashboard is at **Account → Payout Settings → Earnings**. It shows:

- **Gross revenue** — total paid by users
- **Platform fee** — Lumio's 30%
- **Processor fees** — payment provider fees
- **Net revenue** — your actual payout amount
- **Pending balance** — amount not yet paid out
- **Paid out** — total paid to date

Earnings are broken down by extension and by month.

## Changing your payout method

You can add or remove payout methods at any time. Changes take effect for the next payout cycle. In-flight transactions that settled before the change are paid out using the method active at settlement time.

## Tax documents

Lumio generates annual earnings summaries available under **Account → Payout Settings → Tax Documents**. These are for informational purposes — consult a tax professional for your local reporting obligations. US developers receive a 1099-K if applicable; EU developers receive a summary of taxable revenue net of VAT.

---

## Examples / Hello World

# Hello World

The minimal Lumio extension — a static text overlay. Use this to verify your local dev setup is working before building anything more complex.

## Project structure

```
my-hello-world/
├── lumio.config.json
├── src/
│   └── layer.tsx
└── package.json
```

## lumio.config.json

```json
{
  "extensionId": "ext_placeholder",
  "name": "Hello World",
  "version": "1.0.0",
  "targets": ["layer"]
}
```

## src/layer.tsx

```tsx
import { Lumio, Box, Text } from "@zaflun/lumio-sdk";

function HelloWorld() {
  return (
    <Box
      style={{
        position: "absolute",
        top: 40,
        left: 40,
        background: "rgba(0, 0, 0, 0.7)",
        borderRadius: 8,
        padding: "12px 20px",
      }}
    >
      <Text content="Hello, Lumio!" variant="heading" />
    </Box>
  );
}

Lumio.render(<HelloWorld />, { target: "layer" });
```

## Running locally

```bash
lumio dev
```

Open the preview URL shown in the terminal. You should see "Hello, Lumio!" in the top-left corner of the overlay preview.

## Next steps

- Add `"editor"` to `targets` and create `src/editor.tsx` to let streamers customize the text
- Use `useLumioConfig()` to read settings the editor saves
- Try the [Scoreboard](/examples/scoreboard) example to see a full end-to-end extension

---

## Examples / Sports Scoreboard

# Sports Scoreboard

A live sports scoreboard overlay that fetches current game scores from the ESPN API. Demonstrates server functions, external API calls, editor configuration, and the layer surface.

## Project structure

```
sports-scoreboard/
├── lumio.config.json
├── src/
│   ├── editor.tsx
│   ├── layer.tsx
│   └── server/
│       └── functions.ts
└── package.json
```

## lumio.config.json

```json
{
  "extensionId": "ext_placeholder",
  "name": "Sports Scoreboard",
  "version": "1.0.0",
  "targets": ["layer", "editor"],
  "server": true,
  "egress": {
    "allowHosts": [
      "site.api.espn.com"
    ]
  },
  "permissions": ["actions:invoke"]
}
```

## src/server/functions.ts

The server function fetches live scoreboard data from ESPN's public API.

```typescript
import { action, v } from "@zaflun/lumio-sdk/server";

interface ESPNCompetitor {
  team: { displayName: string; abbreviation: string };
  score: string;
}

interface ESPNEvent {
  name: string;
  status: { type: { description: string; completed: boolean } };
  competitions: Array<{
    competitors: ESPNCompetitor[];
  }>;
}

export const getScoreboard = action({
  args: {
    sport: v.string(),
    league: v.string(),
  },
  handler: async (ctx, args) => {
    const res = await ctx.fetch(
      `https://site.api.espn.com/apis/site/v2/sports/${encodeURIComponent(args.sport)}/${encodeURIComponent(args.league)}/scoreboard`
    );

    if (!res.ok) {
      throw new Error(`ESPN API error: ${res.status}`);
    }

    const data = await res.json();
    const events: ESPNEvent[] = data.events ?? [];

    return events.slice(0, 6).map((event) => {
      const comp = event.competitions[0];
      const [away, home] = comp.competitors;
      return {
        name: event.name,
        status: event.status.type.description,
        completed: event.status.type.completed,
        homeTeam: home.team.abbreviation,
        awayTeam: away.team.abbreviation,
        homeScore: home.score,
        awayScore: away.score,
      };
    });
  },
});
```

## src/editor.tsx

The editor lets the streamer choose which sport and league to display.

```tsx
import { Lumio, Box, Text, Select, useLumioConfig } from "@zaflun/lumio-sdk";

const SPORT_OPTIONS = [
  { value: "basketball/nba", label: "NBA Basketball" },
  { value: "football/nfl", label: "NFL Football" },
  { value: "baseball/mlb", label: "MLB Baseball" },
  { value: "hockey/nhl", label: "NHL Hockey" },
  { value: "soccer/usa.1", label: "MLS Soccer" },
];

function ScoreboardEditor() {
  const { config, setConfig } = useLumioConfig<{ league: string }>();
  const selectedLeague = config?.league ?? "basketball/nba";

  return (
    <Box style={{ padding: 20, display: "flex", flexDirection: "column", gap: 16 }}>
      <Text content="Scoreboard Settings" variant="heading" />
      <Box style={{ display: "flex", flexDirection: "column", gap: 8 }}>
        <Text content="Sport / League" variant="label" />
        <Select
          value={selectedLeague}
          options={SPORT_OPTIONS}
          onChange={(value) => setConfig({ league: value })}
        />
      </Box>
    </Box>
  );
}

Lumio.render(<ScoreboardEditor />, { target: "editor" });
```

## src/layer.tsx

The layer displays scores, refreshing every 60 seconds.

```tsx
import { Lumio, Box, Text, useLumioConfig, useLumioAction } from "@zaflun/lumio-sdk";
import { useState, useEffect, useCallback } from "react";

interface GameScore {
  name: string;
  status: string;
  completed: boolean;
  homeTeam: string;
  awayTeam: string;
  homeScore: string;
  awayScore: string;
}

function Scoreboard() {
  const { config } = useLumioConfig<{ league: string }>();
  const { invoke } = useLumioAction("getScoreboard");
  const [games, setGames] = useState<GameScore[]>([]);
  const [loading, setLoading] = useState(true);

  const league = config?.league ?? "basketball/nba";
  const [sport, leagueName] = league.split("/");

  const refresh = useCallback(async () => {
    try {
      const result = await invoke({ sport, league: leagueName });
      setGames(result as GameScore[]);
    } catch {
      // Silently retain previous data on error
    } finally {
      setLoading(false);
    }
  }, [invoke, sport, leagueName]);

  useEffect(() => {
    refresh();
    const interval = setInterval(refresh, 60_000);
    return () => clearInterval(interval);
  }, [refresh]);

  if (loading) return null;
  if (games.length === 0) return null;

  return (
    <Box
      style={{
        position: "absolute",
        top: 20,
        right: 20,
        display: "flex",
        flexDirection: "column",
        gap: 6,
        minWidth: 200,
      }}
    >
      {games.map((game, i) => (
        <Box
          key={i}
          style={{
            background: "rgba(0, 0, 0, 0.75)",
            borderRadius: 6,
            padding: "8px 12px",
            display: "flex",
            justifyContent: "space-between",
            alignItems: "center",
            gap: 12,
          }}
        >
          <Text content={`${game.awayTeam} ${game.awayScore}`} variant="default" />
          <Text content={game.status} variant="muted" style={{ fontSize: 10 }} />
          <Text content={`${game.homeScore} ${game.homeTeam}`} variant="default" />
        </Box>
      ))}
    </Box>
  );
}

Lumio.render(<Scoreboard />, { target: "layer" });
```

## Step-by-step walkthrough

1. **`lumio.config.json`** — declares `"server": true` to enable server functions, and lists `site.api.espn.com` in `allowHosts` so `ctx.fetch()` can reach it.

2. **`server/functions.ts`** — defines a `getScoreboard` action that accepts `sport` and `league` strings, fetches the ESPN scoreboard, and returns a simplified list of game objects.

3. **`editor.tsx`** — renders a `Select` dropdown in the editor panel. The selected value is saved via `setConfig()` and becomes available in the layer via `useLumioConfig()`.

4. **`layer.tsx`** — calls `useLumioAction("getScoreboard")` to get an `invoke` function, then calls it with the configured sport/league on mount and every 60 seconds. Results are stored in local React state and rendered as a list of score rows.

## Key concepts demonstrated

- `useLumioAction` — calling a server function from the layer
- `useLumioConfig` — reading editor-set configuration in the layer
- `ctx.fetch()` — calling an external API from a server function
- `egress.allowHosts` — declaring which external hosts a server function may reach

---

## Examples / Interactive Poll

# Interactive Poll

An interactive poll widget that lets the streamer create polls from the editor panel, lets chat viewers vote via the interactive page, and displays live results on the layer overlay. Demonstrates all three surfaces working together with server-side persistence.

## Project structure

```
poll-widget/
├── lumio.config.json
├── src/
│   ├── editor.tsx
│   ├── layer.tsx
│   ├── interactive.tsx
│   └── server/
│       └── functions.ts
└── package.json
```

## lumio.config.json

```json
{
  "extensionId": "ext_placeholder",
  "name": "Interactive Poll",
  "version": "1.0.0",
  "targets": ["layer", "editor", "interactive"],
  "server": true,
  "permissions": ["actions:invoke", "storage:read", "storage:write"]
}
```

## src/server/functions.ts

```typescript
import { action, query, v } from "@zaflun/lumio-sdk/server";

interface Poll {
  question: string;
  options: string[];
  votes: Record<string, number>;
  active: boolean;
}

// Create or replace the active poll
export const setPoll = action({
  args: {
    question: v.string(),
    options: v.array(v.string()),
  },
  handler: async (ctx, args) => {
    const poll: Poll = {
      question: args.question,
      options: args.options,
      votes: Object.fromEntries(args.options.map((opt) => [opt, 0])),
      active: true,
    };
    await ctx.db.set("global", "poll", poll);
    await ctx.realtime.push("poll:updated", poll);
    return poll;
  },
});

// Register a viewer's vote
export const vote = action({
  args: {
    option: v.string(),
    viewerId: v.string(),
  },
  handler: async (ctx, args) => {
    const poll = await ctx.db.get<Poll>("global", "poll");
    if (!poll || !poll.active) throw new Error("No active poll");
    if (!poll.options.includes(args.option)) throw new Error("Invalid option");

    // Prevent double-voting
    const voteKey = `vote:${args.viewerId}`;
    const hasVoted = await ctx.db.get<boolean>("global", voteKey);
    if (hasVoted) throw new Error("Already voted");

    poll.votes[args.option] = (poll.votes[args.option] ?? 0) + 1;
    await ctx.db.set("global", "poll", poll);
    await ctx.db.set("global", voteKey, true);
    await ctx.realtime.push("poll:updated", poll);
    return poll;
  },
});

// Read the current poll state
export const getPoll = query({
  args: {},
  handler: async (ctx) => {
    return ctx.db.get<Poll>("global", "poll");
  },
});

// Close the poll
export const closePoll = action({
  args: {},
  handler: async (ctx) => {
    const poll = await ctx.db.get<Poll>("global", "poll");
    if (!poll) throw new Error("No poll");
    poll.active = false;
    await ctx.db.set("global", "poll", poll);
    await ctx.realtime.push("poll:updated", poll);
    return poll;
  },
});
```

## src/editor.tsx

```tsx
import { Lumio, Box, Text, Input, Button, useLumioAction } from "@zaflun/lumio-sdk";
import { useState } from "react";

function PollEditor() {
  const { invoke: setPoll, loading } = useLumioAction("setPoll");
  const { invoke: closePoll } = useLumioAction("closePoll");
  const [question, setQuestion] = useState("");
  const [options, setOptions] = useState(["", ""]);

  const addOption = () => setOptions([...options, ""]);
  const updateOption = (i: number, value: string) => {
    const next = [...options];
    next[i] = value;
    setOptions(next);
  };

  const handleStart = async () => {
    const validOptions = options.filter((o) => o.trim().length > 0);
    if (!question.trim() || validOptions.length < 2) return;
    await setPoll({ question: question.trim(), options: validOptions });
    setQuestion("");
    setOptions(["", ""]);
  };

  return (
    <Box style={{ padding: 20, display: "flex", flexDirection: "column", gap: 16 }}>
      <Text content="Create Poll" variant="heading" />
      <Input
        label="Question"
        value={question}
        onChange={setQuestion}
        placeholder="What should I play next?"
      />
      {options.map((opt, i) => (
        <Input
          key={i}
          label={`Option ${i + 1}`}
          value={opt}
          onChange={(v) => updateOption(i, v)}
          placeholder={`Option ${i + 1}`}
        />
      ))}
      <Button label="Add Option" onClick={addOption} variant="secondary" />
      <Button label="Start Poll" onClick={handleStart} loading={loading} />
      <Button label="Close Poll" onClick={() => closePoll({})} variant="danger" />
    </Box>
  );
}

Lumio.render(<PollEditor />, { target: "editor" });
```

## src/interactive.tsx

The interactive page is opened by viewers in their browser. It shows the poll and lets them vote.

```tsx
import { Lumio, Box, Text, Button, useLumioAction, useQuery } from "@zaflun/lumio-sdk";
import { useState } from "react";

interface Poll {
  question: string;
  options: string[];
  votes: Record<string, number>;
  active: boolean;
}

function PollVoting() {
  const { data: poll, loading } = useQuery<Poll>("getPoll", {});
  const { invoke: vote, loading: voting } = useLumioAction("vote");
  const [voted, setVoted] = useState(false);
  const [selected, setSelected] = useState<string | null>(null);

  if (loading) return <Text content="Loading poll..." variant="muted" />;
  if (!poll || !poll.active) return <Text content="No active poll right now." variant="muted" />;

  const totalVotes = Object.values(poll.votes).reduce((a, b) => a + b, 0);

  const handleVote = async () => {
    if (!selected) return;
    const viewerId = crypto.randomUUID(); // In production, use the identity from useLumioIdentity()
    await vote({ option: selected, viewerId });
    setVoted(true);
  };

  return (
    <Box style={{ padding: 24, maxWidth: 480, margin: "0 auto" }}>
      <Text content={poll.question} variant="heading" />
      <Box style={{ display: "flex", flexDirection: "column", gap: 12, marginTop: 16 }}>
        {poll.options.map((opt) => {
          const count = poll.votes[opt] ?? 0;
          const pct = totalVotes > 0 ? Math.round((count / totalVotes) * 100) : 0;
          return (
            <Box
              key={opt}
              onClick={() => !voted && setSelected(opt)}
              style={{
                border: `2px solid ${selected === opt ? "#6366f1" : "#374151"}`,
                borderRadius: 8,
                padding: "12px 16px",
                cursor: voted ? "default" : "pointer",
                position: "relative",
                overflow: "hidden",
              }}
            >
              {voted && (
                <Box
                  style={{
                    position: "absolute",
                    inset: 0,
                    background: "rgba(99,102,241,0.15)",
                    width: `${pct}%`,
                  }}
                />
              )}
              <Box style={{ display: "flex", justifyContent: "space-between" }}>
                <Text content={opt} variant="default" />
                {voted && <Text content={`${pct}%`} variant="muted" />}
              </Box>
            </Box>
          );
        })}
      </Box>
      {!voted && (
        <Button
          label="Vote"
          onClick={handleVote}
          loading={voting}
          style={{ marginTop: 16, width: "100%" }}
        />
      )}
      {voted && <Text content="Thanks for voting!" variant="muted" style={{ marginTop: 12 }} />}
    </Box>
  );
}

Lumio.render(<PollVoting />, { target: "interactive" });
```

## src/layer.tsx

The layer shows live results on the overlay, updating in real time via WebSocket.

```tsx
import { Lumio, Box, Text, useLumioAction } from "@zaflun/lumio-sdk";
import { useState, useEffect } from "react";

interface Poll {
  question: string;
  options: string[];
  votes: Record<string, number>;
  active: boolean;
}

function PollOverlay() {
  const { invoke: getPoll } = useLumioAction("getPoll");
  const [poll, setPoll] = useState<Poll | null>(null);

  useEffect(() => {
    getPoll({}).then((p) => setPoll(p as Poll | null));

    // Real-time updates via WebSocket
    const handler = (event: MessageEvent) => {
      if (event.type === "poll:updated") {
        setPoll(event.data as Poll);
      }
    };
    window.addEventListener("lumio:realtime", handler);
    return () => window.removeEventListener("lumio:realtime", handler);
  }, [getPoll]);

  if (!poll || !poll.active) return null;

  const totalVotes = Object.values(poll.votes).reduce((a, b) => a + b, 0);

  return (
    <Box
      style={{
        position: "absolute",
        top: 20,
        left: 20,
        background: "rgba(0,0,0,0.8)",
        borderRadius: 10,
        padding: "16px 20px",
        minWidth: 280,
      }}
    >
      <Text content={poll.question} variant="heading" style={{ marginBottom: 12 }} />
      {poll.options.map((opt) => {
        const count = poll.votes[opt] ?? 0;
        const pct = totalVotes > 0 ? Math.round((count / totalVotes) * 100) : 0;
        return (
          <Box key={opt} style={{ marginBottom: 8 }}>
            <Box style={{ display: "flex", justifyContent: "space-between", marginBottom: 3 }}>
              <Text content={opt} variant="default" style={{ fontSize: 13 }} />
              <Text content={`${pct}%`} variant="muted" style={{ fontSize: 13 }} />
            </Box>
            <Box style={{ height: 6, background: "#1f2937", borderRadius: 3 }}>
              <Box
                style={{
                  height: 6,
                  width: `${pct}%`,
                  background: "#6366f1",
                  borderRadius: 3,
                  transition: "width 0.4s ease",
                }}
              />
            </Box>
          </Box>
        );
      })}
      <Text content={`${totalVotes} votes`} variant="muted" style={{ fontSize: 11, marginTop: 8 }} />
    </Box>
  );
}

Lumio.render(<PollOverlay />, { target: "layer" });
```

## Key concepts demonstrated

- **Three surfaces** — editor creates the poll, interactive page handles viewer voting, layer shows live results
- **`ctx.realtime.push()`** — pushes poll updates to all connected surfaces via WebSocket
- **`ctx.db.set/get`** — persists poll state in global scoped storage across invocations
- **`useQuery`** — fetches initial poll state declaratively
- **Double-vote prevention** — stores a per-viewer flag in global storage

---

## Examples / Chat Overlay

# Chat Overlay

A scrolling chat display overlay that shows messages from all connected platforms in real time. Demonstrates `useLumioEvent` with the `"chat:message"` event, message queuing, and theme-aware styling.

## Project structure

```
chat-overlay/
├── lumio.config.json
├── src/
│   ├── editor.tsx
│   └── layer.tsx
└── package.json
```

## lumio.config.json

```json
{
  "extensionId": "ext_placeholder",
  "name": "Chat Overlay",
  "version": "1.0.0",
  "targets": ["layer", "editor"],
  "permissions": ["events:read"]
}
```

## src/editor.tsx

```tsx
import { Lumio, Box, Text, Select, Toggle, useLumioConfig } from "@zaflun/lumio-sdk";

interface ChatConfig {
  maxMessages: number;
  showBadges: boolean;
  showPlatformIcon: boolean;
  fontSize: number;
}

const DEFAULT_CONFIG: ChatConfig = {
  maxMessages: 20,
  showBadges: true,
  showPlatformIcon: true,
  fontSize: 14,
};

const FONT_SIZE_OPTIONS = [
  { value: "12", label: "Small (12px)" },
  { value: "14", label: "Medium (14px)" },
  { value: "16", label: "Large (16px)" },
  { value: "20", label: "Extra Large (20px)" },
];

function ChatEditor() {
  const { config, setConfig } = useLumioConfig<ChatConfig>();
  const cfg = { ...DEFAULT_CONFIG, ...config };

  return (
    <Box style={{ padding: 20, display: "flex", flexDirection: "column", gap: 16 }}>
      <Text content="Chat Overlay Settings" variant="heading" />

      <Select
        label="Font Size"
        value={String(cfg.fontSize)}
        options={FONT_SIZE_OPTIONS}
        onChange={(v) => setConfig({ fontSize: Number(v) })}
      />

      <Toggle
        label="Show badges"
        checked={cfg.showBadges}
        onChange={(v) => setConfig({ showBadges: v })}
      />

      <Toggle
        label="Show platform icon"
        checked={cfg.showPlatformIcon}
        onChange={(v) => setConfig({ showPlatformIcon: v })}
      />
    </Box>
  );
}

Lumio.render(<ChatEditor />, { target: "editor" });
```

## src/layer.tsx

```tsx
import { Lumio, Box, Text, useLumioEvent, useLumioConfig, useLumioTheme } from "@zaflun/lumio-sdk";
import { useState, useEffect, useRef } from "react";

interface ChatMessage {
  id: string;
  platform: string;
  userName: string;
  message: string;
  badges: string[];
  timestamp: number;
}

interface ChatConfig {
  maxMessages: number;
  showBadges: boolean;
  showPlatformIcon: boolean;
  fontSize: number;
}

const PLATFORM_COLORS: Record<string, string> = {
  twitch: "#9146ff",
  youtube: "#ff0000",
  kick: "#53fc19",
  trovo: "#26c3a8",
};

const PLATFORM_LABELS: Record<string, string> = {
  twitch: "T",
  youtube: "YT",
  kick: "K",
  trovo: "TR",
};

const DEFAULT_CONFIG: ChatConfig = {
  maxMessages: 20,
  showBadges: true,
  showPlatformIcon: true,
  fontSize: 14,
};

function ChatOverlay() {
  const event = useLumioEvent("chat:message");
  const { config } = useLumioConfig<ChatConfig>();
  const theme = useLumioTheme();
  const [messages, setMessages] = useState<ChatMessage[]>([]);
  const listRef = useRef<HTMLDivElement>(null);

  const cfg = { ...DEFAULT_CONFIG, ...config };

  useEffect(() => {
    if (!event) return;
    const msg: ChatMessage = {
      id: `${event.timestamp}-${event.data.userId}`,
      platform: event.data.platform,
      userName: event.data.userName,
      message: event.data.message,
      badges: event.data.badges ?? [],
      timestamp: Date.now(),
    };
    setMessages((prev) => [...prev, msg].slice(-cfg.maxMessages));
  }, [event, cfg.maxMessages]);

  // Auto-scroll to bottom
  useEffect(() => {
    if (listRef.current) {
      listRef.current.scrollTop = listRef.current.scrollHeight;
    }
  }, [messages]);

  return (
    <Box
      style={{
        position: "absolute",
        bottom: 20,
        left: 20,
        width: 340,
        maxHeight: 480,
        display: "flex",
        flexDirection: "column",
        gap: 0,
        overflow: "hidden",
      }}
    >
      <Box
        ref={listRef}
        style={{
          display: "flex",
          flexDirection: "column",
          gap: 4,
          overflowY: "auto",
          scrollbarWidth: "none",
        }}
      >
        {messages.map((msg) => (
          <Box
            key={msg.id}
            style={{
              background: theme.mode === "dark"
                ? "rgba(0,0,0,0.7)"
                : "rgba(255,255,255,0.85)",
              borderRadius: 6,
              padding: "6px 10px",
              display: "flex",
              flexDirection: "column",
              gap: 2,
            }}
          >
            <Box style={{ display: "flex", alignItems: "center", gap: 6 }}>
              {cfg.showPlatformIcon && (
                <Box
                  style={{
                    background: PLATFORM_COLORS[msg.platform] ?? "#6366f1",
                    borderRadius: 3,
                    padding: "1px 4px",
                    fontSize: 9,
                    fontWeight: 700,
                    color: "#fff",
                  }}
                >
                  <Text
                    content={PLATFORM_LABELS[msg.platform] ?? msg.platform.toUpperCase()}
                    variant="default"
                    style={{ fontSize: 9, fontWeight: 700, color: "#fff" }}
                  />
                </Box>
              )}
              <Text
                content={msg.userName}
                variant="default"
                style={{ fontSize: cfg.fontSize, fontWeight: 600, color: "#6366f1" }}
              />
            </Box>
            <Text
              content={msg.message}
              variant="default"
              style={{ fontSize: cfg.fontSize, lineHeight: 1.4 }}
            />
          </Box>
        ))}
      </Box>
    </Box>
  );
}

Lumio.render(<ChatOverlay />, { target: "layer" });
```

## Key concepts demonstrated

- **`useLumioEvent("chat:message")`** — receives chat messages from all connected platforms (Twitch, YouTube, Kick, Trovo)
- **Message queue** — maintains a bounded list of recent messages using `slice(-maxMessages)` to prevent unbounded growth
- **`useLumioTheme()`** — adapts background color to the streamer's chosen light/dark theme
- **`useLumioConfig()`** — reads editor-set settings like font size and badge visibility
- **Auto-scroll** — a `useRef` + `useEffect` pattern keeps the chat list scrolled to the latest message

## The `chat:message` event payload

```typescript
interface ChatMessageEvent {
  platform: "twitch" | "youtube" | "kick" | "trovo";
  userName: string;
  userId: string;
  message: string;
  emotes: Array<{ id: string; name: string; url: string }>;
  badges: string[]; // e.g. ["subscriber", "moderator"]
  color?: string;  // Twitch chat color, hex
}
```

---

## Examples / Alert Box

# Alert Box

A Twitch follower alert that plays an animated notification when a new follower arrives. Demonstrates `useLumioEvent`, CSS keyframe animations via `defineKeyframes`, and auto-dismiss timers.

## Project structure

```
alert-box/
├── lumio.config.json
├── src/
│   └── layer.tsx
└── package.json
```

## lumio.config.json

```json
{
  "extensionId": "ext_placeholder",
  "name": "Alert Box",
  "version": "1.0.0",
  "targets": ["layer"],
  "permissions": ["events:read"]
}
```

## src/layer.tsx

```tsx
import { Lumio, Box, Text, useLumioEvent, defineKeyframes } from "@zaflun/lumio-sdk";
import { useState, useEffect, useRef } from "react";

// Define CSS keyframe animations
const slideIn = defineKeyframes({
  from: { opacity: 0, transform: "translateY(-40px)" },
  to: { opacity: 1, transform: "translateY(0)" },
});

const fadeOut = defineKeyframes({
  from: { opacity: 1, transform: "translateY(0)" },
  to: { opacity: 0, transform: "translateY(-20px)" },
});

interface AlertItem {
  id: string;
  name: string;
  phase: "in" | "visible" | "out";
}

const DISPLAY_DURATION_MS = 4_000;
const OUT_DURATION_MS = 500;

function AlertBox() {
  const event = useLumioEvent("twitch:follower");
  const [alerts, setAlerts] = useState<AlertItem[]>([]);
  const timersRef = useRef<Map<string, ReturnType<typeof setTimeout>>>(new Map());

  useEffect(() => {
    if (!event) return;

    const id = `${event.timestamp}-${event.data.userId}`;
    const newAlert: AlertItem = { id, name: event.data.userName, phase: "in" };

    setAlerts((prev) => [...prev, newAlert]);

    // Transition to "visible" after animation completes (~600ms)
    const inTimer = setTimeout(() => {
      setAlerts((prev) =>
        prev.map((a) => (a.id === id ? { ...a, phase: "visible" } : a))
      );
    }, 600);

    // Transition to "out" after display duration
    const outTimer = setTimeout(() => {
      setAlerts((prev) =>
        prev.map((a) => (a.id === id ? { ...a, phase: "out" } : a))
      );

      // Remove after out animation
      const removeTimer = setTimeout(() => {
        setAlerts((prev) => prev.filter((a) => a.id !== id));
        timersRef.current.delete(id);
      }, OUT_DURATION_MS);

      timersRef.current.set(`${id}-remove`, removeTimer);
    }, DISPLAY_DURATION_MS);

    timersRef.current.set(`${id}-in`, inTimer);
    timersRef.current.set(`${id}-out`, outTimer);

    return () => {
      // Cleanup on unmount
      timersRef.current.forEach(clearTimeout);
    };
  }, [event]);

  if (alerts.length === 0) return null;

  return (
    <Box
      style={{
        position: "absolute",
        top: 60,
        left: "50%",
        transform: "translateX(-50%)",
        display: "flex",
        flexDirection: "column",
        alignItems: "center",
        gap: 12,
        pointerEvents: "none",
      }}
    >
      {alerts.map((alert) => (
        <Box
          key={alert.id}
          style={{
            background: "linear-gradient(135deg, #6366f1, #8b5cf6)",
            borderRadius: 12,
            padding: "16px 28px",
            minWidth: 280,
            textAlign: "center",
            boxShadow: "0 8px 32px rgba(99,102,241,0.4)",
            animation:
              alert.phase === "in"
                ? `${slideIn} 0.6s cubic-bezier(0.34, 1.56, 0.64, 1) forwards`
                : alert.phase === "out"
                ? `${fadeOut} ${OUT_DURATION_MS}ms ease forwards`
                : undefined,
          }}
        >
          <Text
            content="New Follower!"
            variant="muted"
            style={{ fontSize: 11, letterSpacing: 2, textTransform: "uppercase", marginBottom: 4 }}
          />
          <Text
            content={alert.name}
            variant="heading"
            style={{ fontSize: 22, fontWeight: 700 }}
          />
          <Text
            content="Thanks for following!"
            variant="muted"
            style={{ fontSize: 13, marginTop: 4 }}
          />
        </Box>
      ))}
    </Box>
  );
}

Lumio.render(<AlertBox />, { target: "layer" });
```

## How it works

1. `useLumioEvent("twitch:follower")` subscribes to Twitch follow events. The hook returns the latest event — the reference changes every time a new event arrives.

2. `useEffect` runs when the event reference changes. Each event gets a unique `id` derived from its timestamp and user ID to handle rapid follows without duplicating alerts.

3. The alert goes through three phases:
   - **`in`** — the slide-in animation plays for ~600ms
   - **`visible`** — the alert holds on screen for `DISPLAY_DURATION_MS`
   - **`out`** — the fade-out animation plays, then the alert is removed from state

4. `defineKeyframes()` generates a unique class name for each keyframe block, avoiding conflicts with other extensions.

## Extending the example

**Add subscriber alerts:**

```tsx
const subEvent = useLumioEvent("twitch:subscribe");

useEffect(() => {
  if (!subEvent) return;
  // Push a different alert type into the queue
}, [subEvent]);
```

**Add a sound with `useLumioSound`:**

Bundle a sound file in your extension by adding it to `lumio.config.json`:

```json
{
  "sounds": [
    { "file": "alert.mp3", "name": "Follow Alert", "default_volume": 0.8 }
  ],
  "permissions": ["sounds:play"]
}
```

Place the file in `dist/sounds/alert.mp3` before deploying. Then use the hook in your layer:

```tsx
import { useLumioSound } from "@zaflun/lumio-sdk";
import { useState, useEffect } from "react";

function AlertBox() {
  const { playSound, getSounds } = useLumioSound();
  const [alertSound, setAlertSound] = useState<{ id: string } | null>(null);

  useEffect(() => {
    getSounds().then((sounds) => {
      setAlertSound(sounds.find((s) => s.name === "Follow Alert") ?? null);
    });
  }, []);

  const handleNewFollower = () => {
    if (alertSound) {
      playSound(alertSound.id, 0.8);
    }
  };
  // ...
}
```

**Queue multiple alert types** by maintaining a typed queue array in state and dequeuing one alert at a time.

---

## Examples / Loyalty Points

# Loyalty Points Bot Module

A bot module that tracks viewer loyalty points, provides a gambling command, counts hype moments via keyword detection, welcomes new subscribers, and sends periodic reminders. Demonstrates `ctx.cache` for fast reads and `ctx.defer()` for background database persistence.

## Project structure

```
loyalty-points/
├── lumio.config.json
├── server/
│   ├── schema.ts
│   └── functions.ts
├── package.json
└── tsconfig.json
```

## lumio.config.json

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "ext_placeholder",
  "name": "Loyalty Points",
  "category": "bot_module",
  "version": "1.0.0",
  "platforms": ["twitch", "youtube", "kick"],
  "server": true,
  "permissions": ["chat:send", "chat:read", "events:read"],
  "triggers": {
    "commands": [
      {
        "name": "points",
        "description": "Show your current points balance",
        "cooldown_global": 5,
        "cooldown_user": 10,
        "min_role": "everyone"
      },
      {
        "name": "gamble",
        "description": "Gamble your points (50/50 chance to double or lose)",
        "cooldown_global": 10,
        "cooldown_user": 30,
        "min_role": "subscriber"
      }
    ],
    "keywords": ["gg", "nice shot", "pog"],
    "events": ["twitch:subscribe", "youtube:member", "kick:subscribe"],
    "timers": [
      {
        "name": "reminder",
        "interval": 300,
        "handler": "periodicReminder"
      }
    ]
  },
  "config_schema": [
    {
      "key": "pointsPerMessage",
      "type": "number",
      "label": "Points earned per message",
      "default_value": 1,
      "required": true
    },
    {
      "key": "gamblingEnabled",
      "type": "boolean",
      "label": "Allow gambling",
      "default_value": true,
      "required": true
    },
    {
      "key": "maxBet",
      "type": "number",
      "label": "Maximum bet amount",
      "default_value": 1000,
      "required": true
    },
    {
      "key": "welcomeBonus",
      "type": "number",
      "label": "Points bonus for new subscribers",
      "default_value": 500,
      "required": true
    }
  ]
}
```

## server/schema.ts

```typescript
import { defineSchema, defineTable, column } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  user_points: defineTable({
    user_id: column.string(),
    platform: column.string(),
    balance: column.number(),
    total_earned: column.number(),
    total_gambled: column.number(),
    last_active: column.number(),
  }),
  point_history: defineTable({
    user_id: column.string(),
    amount: column.number(),
    reason: column.string(),
    timestamp: column.number(),
  }),
  hype_log: defineTable({
    user_id: column.string(),
    keyword: column.string(),
    timestamp: column.number(),
  }),
});
```

## server/functions.ts

```typescript
import { command, keyword, event, timer } from "@zaflun/lumio-sdk/server";

// !points — Show current balance
// Uses cache-first pattern: read from cache (~1ms), fall back to DB if cache miss
export const points = command("points", async (ctx, args) => {
  const userId = ctx.user.id;

  // Try cache first
  let balance = (await ctx.cache.get(`pts:${userId}`)) as number | null;

  if (balance === null) {
    // Cache miss — read from DB and populate cache
    const record = await ctx.db.get("user_points", userId);
    balance = (record?.balance as number) ?? 0;
    await ctx.cache.set(`pts:${userId}`, balance, 3600);
  }

  return { reply: `${ctx.user.displayName}: ${balance} points` };
});

// !gamble <amount> — 50/50 chance to double or lose
export const gamble = command("gamble", async (ctx, args) => {
  const gamblingEnabled = (ctx.config.gamblingEnabled as boolean) ?? true;
  if (!gamblingEnabled) {
    return { reply: `${ctx.user.name}, gambling is disabled.` };
  }

  const maxBet = (ctx.config.maxBet as number) ?? 1000;
  const betAmount = Math.min(parseInt(args[0] ?? "0", 10), maxBet);

  if (isNaN(betAmount) || betAmount <= 0) {
    return { reply: `${ctx.user.name}, usage: !gamble <amount> (max: ${maxBet})` };
  }

  // Read current balance from cache or DB
  let balance = (await ctx.cache.get(`pts:${ctx.user.id}`)) as number | null;
  if (balance === null) {
    const record = await ctx.db.get("user_points", ctx.user.id);
    balance = (record?.balance as number) ?? 0;
  }

  if (balance < betAmount) {
    return { reply: `${ctx.user.name}, you only have ${balance} points.` };
  }

  // 50/50 gamble
  const won = Math.random() >= 0.5;
  const newBalance = won ? balance + betAmount : balance - betAmount;

  // Update cache immediately
  await ctx.cache.set(`pts:${ctx.user.id}`, newBalance, 3600);

  // Persist to DB in background
  ctx.defer(async () => {
    await ctx.db.patch("user_points", ctx.user.id, {
      balance: newBalance,
      total_gambled: (balance ?? 0) + betAmount,
    });
    await ctx.db.insert("point_history", {
      user_id: ctx.user.id,
      amount: won ? betAmount : -betAmount,
      reason: "gamble",
      timestamp: Date.now(),
    });
  });

  if (won) {
    return { reply: `${ctx.user.displayName} won ${betAmount} points! New balance: ${newBalance}` };
  }
  return { reply: `${ctx.user.displayName} lost ${betAmount} points. Balance: ${newBalance}` };
});

// Keyword handler — fires on "gg", "nice shot", or "pog"
export const hypeDetector = keyword("gg", async (ctx, message) => {
  // Increment hype counter in cache
  const hypeCount = await ctx.cache.increment("hype_count", 1);

  // Log to DB in background
  ctx.defer(async () => {
    await ctx.db.insert("hype_log", {
      user_id: ctx.user.id,
      keyword: message.text,
      timestamp: Date.now(),
    });
  });

  // Only reply on milestone hype counts
  if (hypeCount % 100 === 0) {
    return { reply: `Hype level: ${hypeCount}!` };
  }
  return null;
});

// Event handler — welcome new subscribers with bonus points
export const welcomeSub = event("twitch:subscribe", async (ctx, evt) => {
  const bonus = (ctx.config.welcomeBonus as number) ?? 500;
  const userName = evt.user_name as string;

  // Add bonus points in background
  ctx.defer(async () => {
    const existing = await ctx.db.get("user_points", evt.user_id as string);
    const currentBalance = (existing?.balance as number) ?? 0;
    if (existing) {
      await ctx.db.patch("user_points", evt.user_id as string, {
        balance: currentBalance + bonus,
        total_earned: ((existing.total_earned as number) ?? 0) + bonus,
      });
    } else {
      await ctx.db.insert("user_points", {
        user_id: evt.user_id,
        platform: "twitch",
        balance: bonus,
        total_earned: bonus,
        total_gambled: 0,
        last_active: Date.now(),
      });
    }
    // Update cache
    await ctx.cache.set(`pts:${evt.user_id}`, currentBalance + bonus, 3600);
  });

  const months = (evt.cumulative_months as number) ?? 1;
  return {
    reply: `Welcome ${userName}! ${months} month(s) strong! You earned ${bonus} bonus points!`,
  };
});

// Timer — periodic reminder every 5 minutes
export const periodicReminder = timer("reminder", async (ctx) => {
  const hypeCount = (await ctx.cache.get("hype_count")) as number ?? 0;
  if (hypeCount > 0) {
    return { reply: `Current hype level: ${hypeCount}! Type !points to check your balance.` };
  }
  return { reply: "Earn points by chatting! Type !points to check your balance." };
});
```

## Key concepts demonstrated

- **Cache-first reads** — `ctx.cache.get()` for ~1ms point balance lookups, falling back to `ctx.db` on cache miss
- **Background persistence** — `ctx.defer()` to write to the database after the handler returns, keeping command responses under the 500ms deadline
- **Atomic increment** — `ctx.cache.increment()` for the hype counter without read-modify-write race conditions
- **Config-driven behavior** — `ctx.config.gamblingEnabled` and `ctx.config.maxBet` let users customize the module
- **Cross-platform events** — the same `welcomeSub` handler works for Twitch, YouTube, and Kick subscriptions
- **Conditional replies** — the keyword handler only replies on milestone counts, staying silent otherwise

---

## Examples / Clip Logger

# Clip Logger Bot Module

A bot module that uses regex pattern matching to detect Twitch clip URLs in chat, stores them in the extension database, and provides a `!clips` command to display recent clips.

## Project structure

```
clip-logger/
├── lumio.config.json
├── server/
│   ├── schema.ts
│   └── functions.ts
├── package.json
└── tsconfig.json
```

## lumio.config.json

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "ext_placeholder",
  "name": "Clip Logger",
  "category": "bot_module",
  "version": "1.0.0",
  "platforms": ["twitch"],
  "server": true,
  "permissions": ["chat:send", "chat:read"],
  "triggers": {
    "commands": [
      {
        "name": "clips",
        "description": "Show the most recent clips shared in chat",
        "cooldown_global": 10,
        "cooldown_user": 30,
        "min_role": "everyone"
      },
      {
        "name": "clipcount",
        "description": "Show total number of clips logged",
        "cooldown_global": 5,
        "cooldown_user": 15,
        "min_role": "everyone"
      }
    ],
    "patterns": [
      "https?://clips\\.twitch\\.tv/\\S+",
      "https?://www\\.twitch\\.tv/\\S+/clip/\\S+"
    ]
  },
  "config_schema": [
    {
      "key": "maxClipsShown",
      "type": "number",
      "label": "Number of clips to show with !clips",
      "default_value": 5,
      "required": true
    },
    {
      "key": "announceClips",
      "type": "boolean",
      "label": "Announce when a clip is detected",
      "default_value": true,
      "required": true
    }
  ]
}
```

## server/schema.ts

```typescript
import { defineSchema, defineTable, column } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  clips: defineTable({
    url: column.string(),
    shared_by: column.string(),
    shared_by_name: column.string(),
    platform: column.string(),
    timestamp: column.number(),
  }),
});
```

## server/functions.ts

```typescript
import { command, pattern } from "@zaflun/lumio-sdk/server";

// Pattern handler — fires when a Twitch clip URL is detected
export const clipDetector = pattern(
  "https?://clips\\.twitch\\.tv/\\S+",
  async (ctx, message, matched) => {
    // Check for duplicate (same URL in the last hour)
    const recentClips = await ctx.db.list("clips");
    const oneHourAgo = Date.now() - 3600000;
    const isDuplicate = recentClips.some(
      (clip) => clip.url === matched && (clip.timestamp as number) > oneHourAgo
    );

    if (isDuplicate) {
      return null; // Silently skip duplicates
    }

    // Store the clip
    ctx.defer(async () => {
      await ctx.db.insert("clips", {
        url: matched,
        shared_by: ctx.user.id,
        shared_by_name: ctx.user.displayName,
        platform: ctx.user.platform,
        timestamp: Date.now(),
      });
    });

    // Increment clip counter in cache
    await ctx.cache.increment("clip_total", 1);

    const announceClips = (ctx.config.announceClips as boolean) ?? true;
    if (announceClips) {
      return { reply: `Clip logged from ${ctx.user.displayName}!` };
    }
    return null;
  }
);

// Also catch the alternate Twitch clip URL format
export const clipDetectorAlt = pattern(
  "https?://www\\.twitch\\.tv/\\S+/clip/\\S+",
  async (ctx, message, matched) => {
    ctx.defer(async () => {
      await ctx.db.insert("clips", {
        url: matched,
        shared_by: ctx.user.id,
        shared_by_name: ctx.user.displayName,
        platform: ctx.user.platform,
        timestamp: Date.now(),
      });
    });

    await ctx.cache.increment("clip_total", 1);

    const announceClips = (ctx.config.announceClips as boolean) ?? true;
    if (announceClips) {
      return { reply: `Clip logged from ${ctx.user.displayName}!` };
    }
    return null;
  }
);

// !clips — Show recent clips
export const clips = command("clips", async (ctx, args) => {
  const maxShown = (ctx.config.maxClipsShown as number) ?? 5;
  const allClips = await ctx.db.list("clips");

  if (allClips.length === 0) {
    return { reply: "No clips have been shared yet!" };
  }

  // Sort by timestamp descending and take the most recent
  const recent = allClips
    .sort((a, b) => (b.timestamp as number) - (a.timestamp as number))
    .slice(0, maxShown);

  const clipList = recent
    .map((clip, i) => `${i + 1}. ${clip.url} (by ${clip.shared_by_name})`)
    .join(" | ");

  return { reply: `Recent clips: ${clipList}` };
});

// !clipcount — Show total clips logged
export const clipcount = command("clipcount", async (ctx, args) => {
  const total = (await ctx.cache.get("clip_total")) as number | null;
  if (total === null) {
    // Cache miss — count from DB
    const allClips = await ctx.db.list("clips");
    await ctx.cache.set("clip_total", allClips.length, 3600);
    return { reply: `Total clips logged: ${allClips.length}` };
  }
  return { reply: `Total clips logged: ${total}` };
});
```

## Key concepts demonstrated

- **Regex pattern triggers** — two patterns catch both Twitch clip URL formats
- **`matched` parameter** — the handler receives the exact URL that matched the pattern
- **Duplicate detection** — checks recent clips to avoid logging the same URL twice
- **Background persistence** — `ctx.defer()` stores clips in the database after responding
- **Cache counters** — `ctx.cache.increment()` for fast total clip counts
- **Config-driven announcements** — the `announceClips` config lets users toggle clip detection messages

---

## Examples / Chat Moderation

# Chat Moderation Bot Module

A bot module that uses the `moderate()` handler to filter chat messages. Demonstrates a link blocklist, timeout escalation (warn, timeout, ban), and audit trail integration.

## Project structure

```
chat-moderation/
├── lumio.config.json
├── server/
│   ├── schema.ts
│   └── functions.ts
├── package.json
└── tsconfig.json
```

## lumio.config.json

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "ext_placeholder",
  "name": "Chat Moderation",
  "category": "bot_module",
  "version": "1.0.0",
  "platforms": ["twitch", "youtube", "kick"],
  "server": true,
  "permissions": ["chat:send", "chat:read", "chat:ban", "chat:delete"],
  "triggers": {
    "commands": [
      {
        "name": "warnings",
        "description": "Check how many warnings a user has",
        "cooldown_global": 5,
        "cooldown_user": 15,
        "min_role": "moderator"
      }
    ],
    "keywords": ["follow me at", "buy followers"]
  },
  "config_schema": [
    {
      "key": "blockedDomains",
      "type": "string",
      "label": "Blocked domains (comma-separated)",
      "default_value": "banned-site.com,scam-link.net",
      "required": true
    },
    {
      "key": "warningsBeforeTimeout",
      "type": "number",
      "label": "Warnings before timeout",
      "default_value": 2,
      "required": true
    },
    {
      "key": "timeoutsBeforeBan",
      "type": "number",
      "label": "Timeouts before ban",
      "default_value": 3,
      "required": true
    },
    {
      "key": "timeoutDuration",
      "type": "number",
      "label": "Timeout duration (seconds)",
      "default_value": 300,
      "required": true
    }
  ]
}
```

## server/schema.ts

```typescript
import { defineSchema, defineTable, column } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  user_infractions: defineTable({
    user_id: column.string(),
    platform: column.string(),
    warnings: column.number(),
    timeouts: column.number(),
    last_infraction: column.number(),
    banned: column.boolean(),
  }),
  infraction_log: defineTable({
    user_id: column.string(),
    user_name: column.string(),
    action: column.string(),
    reason: column.string(),
    timestamp: column.number(),
  }),
});
```

## server/functions.ts

```typescript
import { command, keyword, moderate } from "@zaflun/lumio-sdk/server";

// Moderation handler — runs on every message that passes built-in module checks
// Sync path: must respond within 500ms
export const linkFilter = moderate(async (ctx, message) => {
  const blockedDomainsRaw = (ctx.config.blockedDomains as string) ?? "";
  const blockedDomains = blockedDomainsRaw.split(",").map((d) => d.trim().toLowerCase());

  const textLower = message.text.toLowerCase();

  // Check for blocked domains
  const matchedDomain = blockedDomains.find((domain) => textLower.includes(domain));

  if (!matchedDomain) {
    return { block: false };
  }

  // Look up user infraction history from cache
  const cacheKey = `infractions:${ctx.user.id}`;
  let warnings = ((await ctx.cache.get(`${cacheKey}:warnings`)) as number) ?? 0;
  let timeouts = ((await ctx.cache.get(`${cacheKey}:timeouts`)) as number) ?? 0;

  const warningsThreshold = (ctx.config.warningsBeforeTimeout as number) ?? 2;
  const timeoutsThreshold = (ctx.config.timeoutsBeforeBan as number) ?? 3;
  const timeoutDuration = (ctx.config.timeoutDuration as number) ?? 300;

  // Escalation logic: warn → timeout → ban
  if (warnings < warningsThreshold) {
    // Warning phase: delete message, send warning
    warnings++;
    await ctx.cache.set(`${cacheKey}:warnings`, warnings, 86400);

    ctx.defer(async () => {
      await logInfraction(ctx, "warning", `Blocked domain: ${matchedDomain}`);
    });

    return {
      block: true,
      action: "delete",
      reason: `Warning ${warnings}/${warningsThreshold}: blocked link (${matchedDomain})`,
    };
  }

  if (timeouts < timeoutsThreshold) {
    // Timeout phase
    timeouts++;
    await ctx.cache.set(`${cacheKey}:timeouts`, timeouts, 86400);

    ctx.defer(async () => {
      await logInfraction(ctx, "timeout", `Blocked domain: ${matchedDomain}`);
    });

    return {
      block: true,
      action: "timeout",
      duration: timeoutDuration,
      reason: `Timeout ${timeouts}/${timeoutsThreshold}: repeated blocked link (${matchedDomain})`,
    };
  }

  // Ban phase
  ctx.defer(async () => {
    await logInfraction(ctx, "ban", `Blocked domain: ${matchedDomain}`);
  });

  return {
    block: true,
    action: "ban",
    reason: `Banned: exceeded timeout limit with repeated blocked links`,
  };
});

// Helper: log an infraction to the database
async function logInfraction(
  ctx: any,
  action: string,
  reason: string
) {
  // Update user record
  const existing = await ctx.db.get("user_infractions", ctx.user.id);
  if (existing) {
    await ctx.db.patch("user_infractions", ctx.user.id, {
      warnings: ((existing.warnings as number) ?? 0) + (action === "warning" ? 1 : 0),
      timeouts: ((existing.timeouts as number) ?? 0) + (action === "timeout" ? 1 : 0),
      banned: action === "ban",
      last_infraction: Date.now(),
    });
  } else {
    await ctx.db.insert("user_infractions", {
      user_id: ctx.user.id,
      platform: ctx.user.platform,
      warnings: action === "warning" ? 1 : 0,
      timeouts: action === "timeout" ? 1 : 0,
      last_infraction: Date.now(),
      banned: action === "ban",
    });
  }

  // Log the infraction
  await ctx.db.insert("infraction_log", {
    user_id: ctx.user.id,
    user_name: ctx.user.displayName,
    action,
    reason,
    timestamp: Date.now(),
  });
}

// Keyword handler — detect self-promotion spam
export const spamDetector = keyword("follow me at", async (ctx, message) => {
  ctx.defer(async () => {
    await logInfraction(ctx, "warning", "Self-promotion spam detected");
  });
  return null; // Moderation handled by moderate(), keyword just logs
});

// !warnings <username> — Check a user's infraction count (moderator only)
export const warnings = command("warnings", async (ctx, args) => {
  const targetName = args[0];
  if (!targetName) {
    return { reply: "Usage: !warnings <username>" };
  }

  // Look up by username in the infraction log
  const allInfractions = await ctx.db.list("user_infractions");
  const infractions = await ctx.db.list("infraction_log");
  const userInfractions = infractions.filter(
    (i) => (i.user_name as string)?.toLowerCase() === targetName.toLowerCase()
  );

  if (userInfractions.length === 0) {
    return { reply: `${targetName} has no infractions.` };
  }

  const warningCount = userInfractions.filter((i) => i.action === "warning").length;
  const timeoutCount = userInfractions.filter((i) => i.action === "timeout").length;
  const banCount = userInfractions.filter((i) => i.action === "ban").length;

  return {
    reply: `${targetName}: ${warningCount} warning(s), ${timeoutCount} timeout(s), ${banCount} ban(s)`,
  };
});
```

## Key concepts demonstrated

- **`moderate()` handler** — sync execution path (500ms deadline), runs on every message after built-in modules pass
- **Escalation logic** — warnings lead to timeouts, which lead to bans. Thresholds are configurable.
- **Cache-based infraction tracking** — `ctx.cache` stores warning/timeout counts with 24-hour TTL for fast lookup during sync moderation
- **Background logging** — `ctx.defer()` persists infraction records to the database after the moderation decision is returned
- **Enhanced review permissions** — `chat:ban` and `chat:delete` trigger enhanced manual review during store approval
- **Config-driven thresholds** — the streamer controls warning limits, timeout duration, and blocked domains through the dashboard settings panel

---

## Examples / Twitch Rewards Bot

# Twitch Rewards Bot Module

A Twitch-only bot module that handles Channel Points reward redemptions. Demonstrates event-based triggers with `twitch:reward`, a reward queue using `ctx.cache`, and auto-responses.

## Project structure

```
twitch-rewards/
├── lumio.config.json
├── server/
│   ├── schema.ts
│   └── functions.ts
├── package.json
└── tsconfig.json
```

## lumio.config.json

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "ext_placeholder",
  "name": "Twitch Rewards Bot",
  "category": "bot_module",
  "version": "1.0.0",
  "platforms": ["twitch"],
  "server": true,
  "permissions": ["chat:send", "events:read"],
  "triggers": {
    "commands": [
      {
        "name": "queue",
        "description": "Show the current reward queue",
        "cooldown_global": 10,
        "cooldown_user": 30,
        "min_role": "everyone"
      },
      {
        "name": "clearqueue",
        "description": "Clear the reward queue",
        "cooldown_global": 5,
        "min_role": "moderator"
      }
    ],
    "events": ["twitch:reward"]
  },
  "config_schema": [
    {
      "key": "maxQueueSize",
      "type": "number",
      "label": "Maximum reward queue size",
      "default_value": 20,
      "required": true
    },
    {
      "key": "announceRewards",
      "type": "boolean",
      "label": "Announce reward redemptions in chat",
      "default_value": true,
      "required": true
    }
  ]
}
```

## server/schema.ts

```typescript
import { defineSchema, defineTable, column } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  reward_history: defineTable({
    user_id: column.string(),
    user_name: column.string(),
    reward_title: column.string(),
    reward_cost: column.number(),
    user_input: column.string(),
    timestamp: column.number(),
  }),
});
```

## server/functions.ts

```typescript
import { command, event } from "@zaflun/lumio-sdk/server";

// Event handler — fires on Channel Points reward redemptions
export const rewardHandler = event("twitch:reward", async (ctx, evt) => {
  const rewardTitle = (evt.reward_title as string) ?? "Unknown Reward";
  const userName = evt.user_name as string;
  const userInput = (evt.user_input as string) ?? "";
  const rewardCost = (evt.reward_cost as number) ?? 0;

  // Add to the reward queue in cache
  const maxQueueSize = (ctx.config.maxQueueSize as number) ?? 20;
  const queueLength = await ctx.cache.increment("queue_length", 1);

  if (queueLength > maxQueueSize) {
    // Queue is full — decrement back and notify
    await ctx.cache.increment("queue_length", -1);
    return { reply: `Sorry ${userName}, the reward queue is full! Try again later.` };
  }

  // Store the reward in the queue
  await ctx.cache.set(`queue:${queueLength}`, JSON.stringify({
    user: userName,
    reward: rewardTitle,
    input: userInput,
    cost: rewardCost,
    time: Date.now(),
  }), 7200); // 2-hour TTL

  // Log to database for history
  ctx.defer(async () => {
    await ctx.db.insert("reward_history", {
      user_id: evt.user_id,
      user_name: userName,
      reward_title: rewardTitle,
      reward_cost: rewardCost,
      user_input: userInput,
      timestamp: Date.now(),
    });
  });

  const announceRewards = (ctx.config.announceRewards as boolean) ?? true;
  if (announceRewards) {
    const inputPart = userInput ? ` — "${userInput}"` : "";
    return {
      reply: `${userName} redeemed "${rewardTitle}" (${rewardCost} pts)${inputPart} [Queue #${queueLength}]`,
    };
  }
  return null;
});

// !queue — Show the current reward queue
export const queue = command("queue", async (ctx, args) => {
  const queueLength = ((await ctx.cache.get("queue_length")) as number) ?? 0;

  if (queueLength === 0) {
    return { reply: "The reward queue is empty!" };
  }

  const items: string[] = [];
  for (let i = 1; i <= Math.min(queueLength, 5); i++) {
    const raw = (await ctx.cache.get(`queue:${i}`)) as string | null;
    if (raw) {
      const entry = JSON.parse(raw);
      items.push(`#${i}: ${entry.user} — ${entry.reward}`);
    }
  }

  const moreText = queueLength > 5 ? ` (+${queueLength - 5} more)` : "";
  return { reply: `Reward queue: ${items.join(" | ")}${moreText}` };
});

// !clearqueue — Clear the reward queue (moderator only)
export const clearqueue = command("clearqueue", async (ctx, args) => {
  const queueLength = ((await ctx.cache.get("queue_length")) as number) ?? 0;

  // Delete all queue entries
  for (let i = 1; i <= queueLength; i++) {
    await ctx.cache.delete(`queue:${i}`);
  }
  await ctx.cache.delete("queue_length");

  return { reply: `Reward queue cleared (${queueLength} item(s) removed).` };
});
```

## Key concepts demonstrated

- **Platform-specific events** — `twitch:reward` fires only on Twitch Channel Points redemptions
- **Single-platform extension** — `platforms: ["twitch"]` restricts this module to Twitch only
- **Cache-based queue** — `ctx.cache` stores the reward queue with a 2-hour TTL, using sequential keys
- **Atomic counter** — `ctx.cache.increment()` manages the queue length without race conditions
- **Role-gated commands** — `!clearqueue` requires moderator role via `min_role: "moderator"`
- **Background history logging** — `ctx.defer()` persists reward redemptions to the database for long-term history

---

## Examples / YouTube Member Bot

# YouTube Member Bot Module

A YouTube-only bot module that welcomes new members and handles Super Chat events. Demonstrates YouTube-specific event types and member-only commands.

## Project structure

```
youtube-member-bot/
├── lumio.config.json
├── server/
│   ├── schema.ts
│   └── functions.ts
├── package.json
└── tsconfig.json
```

## lumio.config.json

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "ext_placeholder",
  "name": "YouTube Member Bot",
  "category": "bot_module",
  "version": "1.0.0",
  "platforms": ["youtube"],
  "server": true,
  "permissions": ["chat:send", "chat:read", "events:read"],
  "triggers": {
    "commands": [
      {
        "name": "memberinfo",
        "description": "Show your membership info",
        "cooldown_global": 5,
        "cooldown_user": 15,
        "min_role": "subscriber"
      },
      {
        "name": "topdonors",
        "description": "Show top Super Chat donors",
        "cooldown_global": 15,
        "cooldown_user": 60,
        "min_role": "everyone"
      }
    ],
    "events": [
      "youtube:member",
      "youtube:superchat",
      "youtube:supersticker",
      "youtube:gift_membership"
    ]
  },
  "config_schema": [
    {
      "key": "welcomeMessage",
      "type": "string",
      "label": "Member welcome message template",
      "default_value": "Welcome to the crew, {name}!",
      "required": true
    },
    {
      "key": "superChatThreshold",
      "type": "number",
      "label": "Minimum Super Chat amount for special thank-you (USD cents)",
      "default_value": 500,
      "required": true
    },
    {
      "key": "topDonorsCount",
      "type": "number",
      "label": "Number of donors to show in !topdonors",
      "default_value": 5,
      "required": true
    }
  ]
}
```

## server/schema.ts

```typescript
import { defineSchema, defineTable, column } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  members: defineTable({
    user_id: column.string(),
    user_name: column.string(),
    joined_at: column.number(),
    membership_months: column.number(),
  }),
  donations: defineTable({
    user_id: column.string(),
    user_name: column.string(),
    amount_cents: column.number(),
    currency: column.string(),
    message: column.string(),
    type: column.string(),
    timestamp: column.number(),
  }),
});
```

## server/functions.ts

```typescript
import { command, event } from "@zaflun/lumio-sdk/server";

// Event handler — new YouTube member
export const memberWelcome = event("youtube:member", async (ctx, evt) => {
  const userName = evt.user_name as string;
  const months = (evt.membership_months as number) ?? 1;

  // Store member record in background
  ctx.defer(async () => {
    const existing = await ctx.db.get("members", evt.user_id as string);
    if (existing) {
      await ctx.db.patch("members", evt.user_id as string, {
        membership_months: months,
      });
    } else {
      await ctx.db.insert("members", {
        user_id: evt.user_id,
        user_name: userName,
        joined_at: Date.now(),
        membership_months: months,
      });
    }
  });

  // Build welcome message from config template
  const template = (ctx.config.welcomeMessage as string) ?? "Welcome, {name}!";
  const message = template
    .replace("{name}", userName)
    .replace("{months}", String(months));

  if (months > 1) {
    return { reply: `${message} ${months} months strong!` };
  }
  return { reply: message };
});

// Event handler — Super Chat
export const superChatHandler = event("youtube:superchat", async (ctx, evt) => {
  const userName = evt.user_name as string;
  const amountCents = (evt.amount_micros as number ?? 0) / 10000; // micros to cents
  const currency = (evt.currency as string) ?? "USD";
  const chatMessage = (evt.message as string) ?? "";
  const threshold = (ctx.config.superChatThreshold as number) ?? 500;

  // Store donation in background
  ctx.defer(async () => {
    await ctx.db.insert("donations", {
      user_id: evt.user_id,
      user_name: userName,
      amount_cents: amountCents,
      currency,
      message: chatMessage,
      type: "superchat",
      timestamp: Date.now(),
    });

    // Update cached leaderboard
    const currentTotal = ((await ctx.cache.get(`donor:${evt.user_id}`)) as number) ?? 0;
    await ctx.cache.set(`donor:${evt.user_id}`, currentTotal + amountCents, 86400);
  });

  const amountFormatted = (amountCents / 100).toFixed(2);

  if (amountCents >= threshold) {
    return {
      reply: `HUGE Super Chat from ${userName}: $${amountFormatted} ${currency}! Thank you so much!`,
    };
  }

  return {
    reply: `Thank you ${userName} for the $${amountFormatted} ${currency} Super Chat!`,
  };
});

// Event handler — Super Sticker
export const superStickerHandler = event("youtube:supersticker", async (ctx, evt) => {
  const userName = evt.user_name as string;
  const amountCents = (evt.amount_micros as number ?? 0) / 10000;
  const currency = (evt.currency as string) ?? "USD";

  ctx.defer(async () => {
    await ctx.db.insert("donations", {
      user_id: evt.user_id,
      user_name: userName,
      amount_cents: amountCents,
      currency,
      message: "",
      type: "supersticker",
      timestamp: Date.now(),
    });
  });

  const amountFormatted = (amountCents / 100).toFixed(2);
  return {
    reply: `${userName} sent a Super Sticker ($${amountFormatted} ${currency})! Thank you!`,
  };
});

// Event handler — Gift Membership
export const giftMembershipHandler = event("youtube:gift_membership", async (ctx, evt) => {
  const userName = evt.user_name as string;
  const giftCount = (evt.gift_count as number) ?? 1;

  ctx.defer(async () => {
    await ctx.db.insert("donations", {
      user_id: evt.user_id,
      user_name: userName,
      amount_cents: 0,
      currency: "",
      message: `Gifted ${giftCount} membership(s)`,
      type: "gift_membership",
      timestamp: Date.now(),
    });
  });

  if (giftCount > 1) {
    return { reply: `${userName} just gifted ${giftCount} memberships! Incredible!` };
  }
  return { reply: `${userName} gifted a membership! Thank you!` };
});

// !memberinfo — Show membership info (members only)
export const memberinfo = command("memberinfo", async (ctx, args) => {
  const member = await ctx.db.get("members", ctx.user.id);
  if (!member) {
    return { reply: `${ctx.user.name}, no membership record found.` };
  }

  const months = member.membership_months as number;
  const joinedDate = new Date(member.joined_at as number).toLocaleDateString();
  return {
    reply: `${ctx.user.displayName}: Member since ${joinedDate}, ${months} month(s)`,
  };
});

// !topdonors — Show top Super Chat donors
export const topdonors = command("topdonors", async (ctx, args) => {
  const count = (ctx.config.topDonorsCount as number) ?? 5;
  const allDonations = await ctx.db.list("donations");

  if (allDonations.length === 0) {
    return { reply: "No donations recorded yet!" };
  }

  // Aggregate totals by user
  const totals: Record<string, { name: string; total: number }> = {};
  for (const d of allDonations) {
    const uid = d.user_id as string;
    if (!totals[uid]) {
      totals[uid] = { name: d.user_name as string, total: 0 };
    }
    totals[uid].total += (d.amount_cents as number) ?? 0;
  }

  // Sort and take top N
  const sorted = Object.values(totals)
    .filter((t) => t.total > 0)
    .sort((a, b) => b.total - a.total)
    .slice(0, count);

  if (sorted.length === 0) {
    return { reply: "No monetary donations recorded yet!" };
  }

  const list = sorted
    .map((t, i) => `${i + 1}. ${t.name}: $${(t.total / 100).toFixed(2)}`)
    .join(" | ");

  return { reply: `Top donors: ${list}` };
});
```

## Key concepts demonstrated

- **YouTube-specific events** — `youtube:member`, `youtube:superchat`, `youtube:supersticker`, `youtube:gift_membership`
- **Single-platform module** — `platforms: ["youtube"]` restricts this to YouTube
- **Config templates** — welcome message uses `{name}` and `{months}` placeholders replaced at runtime
- **Member-only commands** — `!memberinfo` uses `min_role: "subscriber"` to restrict access to members
- **Background data persistence** — all event data is stored via `ctx.defer()` to keep sync handlers fast
- **Aggregated leaderboard** — `!topdonors` aggregates donation data from the database

---

## Examples / Kick Follow Bot

# Kick Follow Bot Module

A Kick-only bot module that announces new followers and tracks follow streaks using `ctx.cache` for fast counter access and `ctx.defer()` for background database persistence.

## Project structure

```
kick-follow-bot/
├── lumio.config.json
├── server/
│   ├── schema.ts
│   └── functions.ts
├── package.json
└── tsconfig.json
```

## lumio.config.json

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "ext_placeholder",
  "name": "Kick Follow Bot",
  "category": "bot_module",
  "version": "1.0.0",
  "platforms": ["kick"],
  "server": true,
  "permissions": ["chat:send", "events:read"],
  "triggers": {
    "commands": [
      {
        "name": "followers",
        "description": "Show the follow streak count for this stream",
        "cooldown_global": 10,
        "cooldown_user": 30,
        "min_role": "everyone"
      },
      {
        "name": "recentfollows",
        "description": "Show the most recent followers",
        "cooldown_global": 10,
        "cooldown_user": 30,
        "min_role": "everyone"
      }
    ],
    "events": ["kick:follower"]
  },
  "config_schema": [
    {
      "key": "announceFollows",
      "type": "boolean",
      "label": "Announce new followers in chat",
      "default_value": true,
      "required": true
    },
    {
      "key": "streakMilestone",
      "type": "number",
      "label": "Follow streak milestone for special message",
      "default_value": 10,
      "required": true
    },
    {
      "key": "welcomeEmote",
      "type": "string",
      "label": "Emote to include in welcome message",
      "default_value": "",
      "required": false
    }
  ]
}
```

## server/schema.ts

```typescript
import { defineSchema, defineTable, column } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  followers: defineTable({
    user_id: column.string(),
    user_name: column.string(),
    followed_at: column.number(),
    stream_session: column.string(),
  }),
});
```

## server/functions.ts

```typescript
import { command, event } from "@zaflun/lumio-sdk/server";

// Event handler — new Kick follower
export const followHandler = event("kick:follower", async (ctx, evt) => {
  const userName = evt.user_name as string;

  // Increment the follow streak counter
  const streakCount = await ctx.cache.increment("follow_streak", 1);

  // Store follower record in background
  ctx.defer(async () => {
    await ctx.db.insert("followers", {
      user_id: evt.user_id,
      user_name: userName,
      followed_at: Date.now(),
      stream_session: await getSessionId(ctx),
    });
  });

  const announceFollows = (ctx.config.announceFollows as boolean) ?? true;
  if (!announceFollows) {
    return null;
  }

  const emote = (ctx.config.welcomeEmote as string) ?? "";
  const emotePart = emote ? ` ${emote}` : "";
  const milestone = (ctx.config.streakMilestone as number) ?? 10;

  // Check for milestone
  if (streakCount > 0 && streakCount % milestone === 0) {
    return {
      reply: `${streakCount} follow streak! Welcome ${userName}!${emotePart} We've hit ${streakCount} new followers this stream!`,
    };
  }

  return {
    reply: `Welcome ${userName}!${emotePart} (Follow #${streakCount} this stream)`,
  };
});

// !followers — Show the current follow streak count
export const followers = command("followers", async (ctx, args) => {
  const streakCount = ((await ctx.cache.get("follow_streak")) as number) ?? 0;

  if (streakCount === 0) {
    return { reply: "No new followers this stream yet!" };
  }

  return { reply: `${streakCount} new follower(s) this stream!` };
});

// !recentfollows — Show the most recent followers
export const recentfollows = command("recentfollows", async (ctx, args) => {
  const allFollowers = await ctx.db.list("followers");

  if (allFollowers.length === 0) {
    return { reply: "No followers recorded yet!" };
  }

  // Sort by timestamp descending, take last 5
  const recent = allFollowers
    .sort((a, b) => (b.followed_at as number) - (a.followed_at as number))
    .slice(0, 5);

  const names = recent.map((f) => f.user_name).join(", ");
  return { reply: `Recent followers: ${names}` };
});

// Helper: get or create a session ID for this stream
async function getSessionId(ctx: any): Promise<string> {
  let sessionId = (await ctx.cache.get("session_id")) as string | null;
  if (!sessionId) {
    sessionId = `session_${Date.now()}`;
    // 12-hour TTL — covers a long stream
    await ctx.cache.set("session_id", sessionId, 43200);
  }
  return sessionId;
}
```

## Key concepts demonstrated

- **Kick-specific events** — `kick:follower` fires when a new viewer follows the Kick channel
- **Single-platform module** — `platforms: ["kick"]` restricts this to Kick only
- **Follow streak tracking** — `ctx.cache.increment()` counts new followers during the stream session
- **Milestone announcements** — special messages at configurable streak intervals (every 10, 25, 50, etc.)
- **Session-scoped data** — cache keys with 12-hour TTL naturally reset between streams
- **Background persistence** — `ctx.defer()` stores follower records in the database while keeping the event handler fast
- **Config-driven behavior** — announce toggle, milestone interval, and custom emote are all configurable

---

## Examples / Discord Moderation Bot

# Discord Moderation Bot Module

A Discord-only bot module that provides `/warn` and `/mute` slash commands, keyword-based auto-moderation, and a member join welcome message. Demonstrates Discord-specific features including `discord_options` for slash command parameters.

## Project structure

```
discord-moderation/
├── lumio.config.json
├── server/
│   ├── schema.ts
│   └── functions.ts
├── package.json
└── tsconfig.json
```

## lumio.config.json

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "ext_placeholder",
  "name": "Discord Moderation Bot",
  "category": "bot_module",
  "version": "1.0.0",
  "platforms": ["discord"],
  "server": true,
  "permissions": ["chat:send", "chat:read", "chat:ban", "chat:delete"],
  "triggers": {
    "commands": [
      {
        "name": "warn",
        "description": "Warn a user for rule violation",
        "cooldown_global": 0,
        "min_role": "moderator",
        "discord_options": [
          {
            "name": "user",
            "type": "user",
            "description": "User to warn",
            "required": true
          },
          {
            "name": "reason",
            "type": "string",
            "description": "Reason for the warning",
            "required": true
          }
        ]
      },
      {
        "name": "mute",
        "description": "Temporarily mute a user",
        "cooldown_global": 0,
        "min_role": "moderator",
        "discord_options": [
          {
            "name": "user",
            "type": "user",
            "description": "User to mute",
            "required": true
          },
          {
            "name": "duration",
            "type": "integer",
            "description": "Mute duration in minutes",
            "required": true
          },
          {
            "name": "reason",
            "type": "string",
            "description": "Reason for the mute",
            "required": false
          }
        ]
      },
      {
        "name": "infractions",
        "description": "View a user's infraction history",
        "cooldown_global": 5,
        "min_role": "moderator",
        "discord_options": [
          {
            "name": "user",
            "type": "user",
            "description": "User to check",
            "required": true
          }
        ]
      }
    ],
    "keywords": ["discord.gg/", "discordapp.com/invite/"],
    "events": ["discord:member_join"]
  },
  "config_schema": [
    {
      "key": "maxWarnings",
      "type": "number",
      "label": "Warnings before auto-mute",
      "default_value": 3,
      "required": true
    },
    {
      "key": "autoMuteDuration",
      "type": "number",
      "label": "Auto-mute duration (minutes)",
      "default_value": 30,
      "required": true
    },
    {
      "key": "welcomeMessage",
      "type": "string",
      "label": "Welcome message for new members",
      "default_value": "Welcome to the server, {name}! Please read the rules.",
      "required": true
    },
    {
      "key": "blockInviteLinks",
      "type": "boolean",
      "label": "Auto-delete Discord invite links from non-mods",
      "default_value": true,
      "required": true
    }
  ]
}
```

## server/schema.ts

```typescript
import { defineSchema, defineTable, column } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  infractions: defineTable({
    user_id: column.string(),
    user_name: column.string(),
    type: column.string(),
    reason: column.string(),
    issued_by: column.string(),
    issued_by_name: column.string(),
    timestamp: column.number(),
  }),
});
```

## server/functions.ts

```typescript
import { command, keyword, event } from "@zaflun/lumio-sdk/server";

// /warn — Issue a warning to a user (Discord slash command)
// args[0] = user ID, args[1] = reason
export const warn = command("warn", async (ctx, args) => {
  const targetUserId = args[0];
  const reason = args[1] ?? "No reason provided";

  if (!targetUserId) {
    return { reply: "Usage: /warn <user> <reason>" };
  }

  // Get current warning count from cache
  const warningKey = `warnings:${targetUserId}`;
  const warningCount = await ctx.cache.increment(warningKey, 1);

  // Set 30-day TTL on first warning
  if (warningCount === 1) {
    await ctx.cache.set(warningKey, 1, 2592000); // 30 days
  }

  // Log infraction in background
  ctx.defer(async () => {
    await ctx.db.insert("infractions", {
      user_id: targetUserId,
      user_name: targetUserId, // Discord resolves the display name
      type: "warning",
      reason,
      issued_by: ctx.user.id,
      issued_by_name: ctx.user.displayName,
      timestamp: Date.now(),
    });
  });

  const maxWarnings = (ctx.config.maxWarnings as number) ?? 3;

  if (warningCount >= maxWarnings) {
    // Auto-mute after reaching threshold
    const muteDuration = (ctx.config.autoMuteDuration as number) ?? 30;

    return {
      reply: `User <@${targetUserId}> has been warned (${warningCount}/${maxWarnings}). Auto-mute applied for ${muteDuration} minutes. Reason: ${reason}`,
      actions: [
        {
          action: "chat:ban",
          params: {
            user_id: targetUserId,
            type: "timeout",
            duration: muteDuration * 60,
            reason: `Auto-mute: ${warningCount} warnings reached. Last: ${reason}`,
          },
        },
      ],
    };
  }

  return {
    reply: `Warning ${warningCount}/${maxWarnings} issued to <@${targetUserId}>. Reason: ${reason}`,
  };
});

// /mute — Temporarily mute a user (Discord slash command)
// args[0] = user ID, args[1] = duration (minutes), args[2] = reason
export const mute = command("mute", async (ctx, args) => {
  const targetUserId = args[0];
  const duration = parseInt(args[1] ?? "10", 10);
  const reason = args[2] ?? "No reason provided";

  if (!targetUserId) {
    return { reply: "Usage: /mute <user> <duration> [reason]" };
  }

  // Log in background
  ctx.defer(async () => {
    await ctx.db.insert("infractions", {
      user_id: targetUserId,
      user_name: targetUserId,
      type: "mute",
      reason,
      issued_by: ctx.user.id,
      issued_by_name: ctx.user.displayName,
      timestamp: Date.now(),
    });
  });

  return {
    reply: `<@${targetUserId}> has been muted for ${duration} minute(s). Reason: ${reason}`,
    actions: [
      {
        action: "chat:ban",
        params: {
          user_id: targetUserId,
          type: "timeout",
          duration: duration * 60,
          reason,
        },
      },
    ],
  };
});

// /infractions — View a user's infraction history
// args[0] = user ID
export const infractions = command("infractions", async (ctx, args) => {
  const targetUserId = args[0];

  if (!targetUserId) {
    return { reply: "Usage: /infractions <user>" };
  }

  const allInfractions = await ctx.db.list("infractions");
  const userInfractions = allInfractions
    .filter((i) => i.user_id === targetUserId)
    .sort((a, b) => (b.timestamp as number) - (a.timestamp as number))
    .slice(0, 10);

  if (userInfractions.length === 0) {
    return { reply: `<@${targetUserId}> has no infractions.` };
  }

  const summary = userInfractions
    .map((i) => {
      const date = new Date(i.timestamp as number).toLocaleDateString();
      return `${i.type}: ${i.reason} (${date})`;
    })
    .join(" | ");

  return {
    reply: `<@${targetUserId}> infractions (${userInfractions.length}): ${summary}`,
  };
});

// Keyword handler — detect Discord invite links
export const inviteLinkFilter = keyword("discord.gg/", async (ctx, message) => {
  const blockInvites = (ctx.config.blockInviteLinks as boolean) ?? true;

  if (!blockInvites) {
    return null;
  }

  // Moderators are exempt
  if (ctx.user.isMod) {
    return null;
  }

  // Log the attempted invite
  ctx.defer(async () => {
    await ctx.db.insert("infractions", {
      user_id: ctx.user.id,
      user_name: ctx.user.displayName,
      type: "auto_delete",
      reason: "Discord invite link posted",
      issued_by: "system",
      issued_by_name: "Auto-mod",
      timestamp: Date.now(),
    });
  });

  return {
    reply: `${ctx.user.name}, invite links are not allowed in this server.`,
    actions: [
      {
        action: "chat:delete",
        params: { message_id: message.platformMessageId },
      },
    ],
  };
});

// Event handler — welcome new Discord server members
export const memberJoinWelcome = event("discord:member_join", async (ctx, evt) => {
  const userName = evt.user_name as string;
  const template = (ctx.config.welcomeMessage as string) ?? "Welcome, {name}!";
  const message = template.replace("{name}", userName);

  return { reply: message };
});
```

## Key concepts demonstrated

- **Discord slash commands** — `discord_options` defines typed parameters for `/warn`, `/mute`, and `/infractions`
- **Discord-only module** — `platforms: ["discord"]` restricts this to Discord servers
- **Auto-escalation** — warnings automatically escalate to mutes after a configurable threshold
- **Keyword auto-moderation** — invite links are detected and auto-deleted for non-moderators
- **Role-based exemptions** — `ctx.user.isMod` checks let moderators bypass auto-mod rules
- **Action responses** — handlers return `actions` array to trigger moderation actions (`chat:ban`, `chat:delete`)
- **Enhanced review permissions** — `chat:ban` and `chat:delete` require enhanced manual review during store approval

---

## Examples / Cross-Platform Stats Bot

# Cross-Platform Stats Bot Module

A bot module that tracks chat statistics across Twitch, YouTube, and Kick simultaneously. Demonstrates multi-platform configuration, cross-platform message handling via keywords, and a unified leaderboard.

## Project structure

```
cross-platform-stats/
├── lumio.config.json
├── server/
│   ├── schema.ts
│   └── functions.ts
├── package.json
└── tsconfig.json
```

## lumio.config.json

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "ext_placeholder",
  "name": "Cross-Platform Chat Stats",
  "category": "bot_module",
  "version": "1.0.0",
  "platforms": ["twitch", "youtube", "kick"],
  "server": true,
  "permissions": ["chat:send", "chat:read", "events:read"],
  "triggers": {
    "commands": [
      {
        "name": "stats",
        "description": "Show your chat stats across all platforms",
        "cooldown_global": 5,
        "cooldown_user": 15,
        "min_role": "everyone"
      },
      {
        "name": "leaderboard",
        "description": "Show the top chatters across all platforms",
        "cooldown_global": 15,
        "cooldown_user": 60,
        "min_role": "everyone"
      },
      {
        "name": "platformstats",
        "description": "Show message count breakdown by platform",
        "cooldown_global": 10,
        "cooldown_user": 30,
        "min_role": "everyone"
      }
    ],
    "events": [
      "twitch:chat",
      "youtube:chat",
      "kick:chat"
    ],
    "timers": [
      {
        "name": "statsSummary",
        "interval": 900,
        "handler": "statsSummary"
      }
    ]
  },
  "config_schema": [
    {
      "key": "leaderboardSize",
      "type": "number",
      "label": "Number of users shown in leaderboard",
      "default_value": 10,
      "required": true
    },
    {
      "key": "trackAllMessages",
      "type": "boolean",
      "label": "Track all messages (not just commands)",
      "default_value": true,
      "required": true
    }
  ]
}
```

## server/schema.ts

```typescript
import { defineSchema, defineTable, column } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  chat_stats: defineTable({
    user_id: column.string(),
    user_name: column.string(),
    platform: column.string(),
    message_count: column.number(),
    first_seen: column.number(),
    last_seen: column.number(),
  }),
});
```

## server/functions.ts

```typescript
import { command, event, timer } from "@zaflun/lumio-sdk/server";

// Event handler — track Twitch chat messages
export const trackTwitchChat = event("twitch:chat", async (ctx, evt) => {
  const trackAll = (ctx.config.trackAllMessages as boolean) ?? true;
  if (!trackAll) return null;

  await trackMessage(ctx, evt.user_id as string, evt.user_name as string, "twitch");
  return null;
});

// Event handler — track YouTube chat messages
export const trackYoutubeChat = event("youtube:chat", async (ctx, evt) => {
  const trackAll = (ctx.config.trackAllMessages as boolean) ?? true;
  if (!trackAll) return null;

  await trackMessage(ctx, evt.user_id as string, evt.user_name as string, "youtube");
  return null;
});

// Event handler — track Kick chat messages
export const trackKickChat = event("kick:chat", async (ctx, evt) => {
  const trackAll = (ctx.config.trackAllMessages as boolean) ?? true;
  if (!trackAll) return null;

  await trackMessage(ctx, evt.user_id as string, evt.user_name as string, "kick");
  return null;
});

// Helper: track a message from any platform
async function trackMessage(ctx: any, userId: string, userName: string, platform: string) {
  // Increment per-platform counter in cache
  const cacheKey = `msgs:${platform}:${userId}`;
  await ctx.cache.increment(cacheKey, 1);

  // Increment total counter
  await ctx.cache.increment(`total:${platform}`, 1);
  await ctx.cache.increment("total:all", 1);

  // Persist to DB in background (batch-friendly — runs after handler returns)
  ctx.defer(async () => {
    const existing = await ctx.db.get("chat_stats", `${userId}:${platform}`);
    if (existing) {
      await ctx.db.patch("chat_stats", `${userId}:${platform}`, {
        message_count: ((existing.message_count as number) ?? 0) + 1,
        last_seen: Date.now(),
        user_name: userName,
      });
    } else {
      await ctx.db.insert("chat_stats", {
        user_id: userId,
        user_name: userName,
        platform,
        message_count: 1,
        first_seen: Date.now(),
        last_seen: Date.now(),
      });
    }
  });
}

// !stats — Show the caller's chat stats across all platforms
export const stats = command("stats", async (ctx, args) => {
  const platforms = ["twitch", "youtube", "kick"];
  const counts: string[] = [];

  for (const platform of platforms) {
    const cached = (await ctx.cache.get(`msgs:${platform}:${ctx.user.id}`)) as number | null;
    if (cached && cached > 0) {
      counts.push(`${platform}: ${cached}`);
    }
  }

  if (counts.length === 0) {
    // Fall back to DB
    const allStats = await ctx.db.list("chat_stats");
    const userStats = allStats.filter((s) => s.user_id === ctx.user.id);
    if (userStats.length === 0) {
      return { reply: `${ctx.user.displayName}, no chat stats recorded yet!` };
    }
    for (const s of userStats) {
      counts.push(`${s.platform}: ${s.message_count}`);
    }
  }

  return { reply: `${ctx.user.displayName}'s chat stats: ${counts.join(" | ")}` };
});

// !leaderboard — Show top chatters across all platforms
export const leaderboard = command("leaderboard", async (ctx, args) => {
  const size = (ctx.config.leaderboardSize as number) ?? 10;
  const allStats = await ctx.db.list("chat_stats");

  if (allStats.length === 0) {
    return { reply: "No chat stats recorded yet!" };
  }

  // Aggregate by user across platforms
  const totals: Record<string, { name: string; total: number }> = {};
  for (const s of allStats) {
    const uid = s.user_id as string;
    if (!totals[uid]) {
      totals[uid] = { name: s.user_name as string, total: 0 };
    }
    totals[uid].total += (s.message_count as number) ?? 0;
  }

  const sorted = Object.values(totals)
    .sort((a, b) => b.total - a.total)
    .slice(0, size);

  const list = sorted
    .map((t, i) => `${i + 1}. ${t.name}: ${t.total}`)
    .join(" | ");

  return { reply: `Chat leaderboard: ${list}` };
});

// !platformstats — Show message count breakdown by platform
export const platformstats = command("platformstats", async (ctx, args) => {
  const platforms = ["twitch", "youtube", "kick"];
  const counts: string[] = [];

  for (const platform of platforms) {
    const total = ((await ctx.cache.get(`total:${platform}`)) as number) ?? 0;
    if (total > 0) {
      counts.push(`${platform}: ${total}`);
    }
  }

  const totalAll = ((await ctx.cache.get("total:all")) as number) ?? 0;

  if (totalAll === 0) {
    return { reply: "No messages tracked yet!" };
  }

  return { reply: `Platform stats (${totalAll} total): ${counts.join(" | ")}` };
});

// Timer — periodic stats summary every 15 minutes
export const statsSummary = timer("statsSummary", async (ctx) => {
  const totalAll = ((await ctx.cache.get("total:all")) as number) ?? 0;

  if (totalAll === 0) {
    return null; // No messages tracked yet, skip this cycle
  }

  const platforms = ["twitch", "youtube", "kick"];
  const counts: string[] = [];

  for (const platform of platforms) {
    const total = ((await ctx.cache.get(`total:${platform}`)) as number) ?? 0;
    if (total > 0) {
      counts.push(`${platform}: ${total}`);
    }
  }

  return {
    reply: `Chat stats update: ${totalAll} messages across ${counts.length} platform(s) (${counts.join(", ")})`,
  };
});
```

## Key concepts demonstrated

- **Multi-platform support** — `platforms: ["twitch", "youtube", "kick"]` receives messages from all three platforms
- **Platform-specific chat events** — separate handlers for `twitch:chat`, `youtube:chat`, and `kick:chat`
- **Cross-platform aggregation** — unified leaderboard combines message counts from all platforms
- **Per-platform cache counters** — `ctx.cache.increment()` tracks totals per platform and per user-platform pair
- **Timer summary** — periodic chat stats broadcast to all connected platforms
- **Shared helper function** — `trackMessage()` centralizes tracking logic for all platforms
- **Cache-first reads** — `!stats` and `!platformstats` read from cache for instant responses
- **Background DB persistence** — `ctx.defer()` writes to the database without blocking the event handler

---

## API Reference / Developer REST API

# Developer REST API

The Lumio Developer REST API allows you to manage extensions, versions, and installs programmatically. It is intended for use in CI/CD pipelines, scripts, and tooling — not in end-user browsers.

## Base URL

```
https://api.lumio.vision/developer/v1
```

## Authentication

All endpoints require a Lumio user API key passed in the `Authorization` header:

```
Authorization: Bearer lm_usr_<your_api_key>
```

API keys are created and revoked under **Dashboard → API Keys**. Each key is scoped to the creating user, the active account, and the permissions selected at creation time.

## Rate limits

| Endpoint group | Limit |
|---------------|-------|
| `GET` endpoints | 120 requests/minute |
| `POST /extensions` | 10 requests/hour |
| `POST /extensions/:id/versions` | 30 requests/hour |
| `DELETE` endpoints | 30 requests/minute |

Exceeding a limit returns `429 Too Many Requests` with a `Retry-After` header (seconds to wait).

## Errors

All errors use the same JSON envelope:

```json
{
  "error": {
    "code": "extension_not_found",
    "message": "Extension ext_abc123 does not exist or you do not have access to it.",
    "status": 404
  }
}
```

Common error codes:

| Code | HTTP status | Description |
|------|------------|-------------|
| `unauthorized` | 401 | Missing or invalid API key |
| `forbidden` | 403 | Valid key but insufficient permissions |
| `not_found` | 404 | Resource does not exist |
| `validation_error` | 422 | Request body failed validation |
| `rate_limited` | 429 | Too many requests |
| `internal_error` | 500 | Unexpected server error |

---

## Extensions

### List extensions

```
GET /extensions
```

Returns all extensions belonging to your developer account.

```bash
curl https://api.lumio.vision/developer/v1/extensions \
  -H "Authorization: Bearer lm_usr_your_key"
```

Response `200`:

```json
{
  "extensions": [
    {
      "id": "ext_01j9k2m3n4p5q6r7",
      "slug": "my-scoreboard",
      "name": "Sports Scoreboard",
      "visibility": "public",
      "status": "approved",
      "installCount": 142,
      "currentVersionId": "ver_abc123",
      "createdAt": "2026-01-15T10:30:00Z",
      "updatedAt": "2026-04-01T08:00:00Z"
    }
  ]
}
```

### Get extension

```
GET /extensions/:id
```

```bash
curl https://api.lumio.vision/developer/v1/extensions/ext_01j9k2m3n4p5q6r7 \
  -H "Authorization: Bearer lm_usr_your_key"
```

Response `200` — full extension object including `pricing`, `description`, and `ratingCount`.

### Create extension

```
POST /extensions
```

```bash
curl -X POST https://api.lumio.vision/developer/v1/extensions \
  -H "Authorization: Bearer lm_usr_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My New Extension",
    "short_description": "A brief description shown in search results.",
    "description": "Full Markdown description.",
    "pricing": { "type": "free" }
  }'
```

Response `201`:

```json
{
  "extension": {
    "id": "ext_newly_created_id",
    "slug": "my-new-extension",
    "name": "My New Extension",
    "status": "draft",
    "createdAt": "2026-05-01T00:00:00Z"
  }
}
```

### Update extension

```
PATCH /extensions/:id
```

Accepts the same fields as `POST /extensions`. Only provided fields are updated.

```bash
curl -X PATCH https://api.lumio.vision/developer/v1/extensions/ext_01j9k2m3n4p5q6r7 \
  -H "Authorization: Bearer lm_usr_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "public" }'
```

Response `200` — updated extension object.

### Delete extension

```
DELETE /extensions/:id
```

Only allowed for extensions that have never been publicly listed.

```bash
curl -X DELETE https://api.lumio.vision/developer/v1/extensions/ext_01j9k2m3n4p5q6r7 \
  -H "Authorization: Bearer lm_usr_your_key"
```

Response `204 No Content`.

---

## Versions

### List versions

```
GET /extensions/:id/versions
```

```bash
curl https://api.lumio.vision/developer/v1/extensions/ext_01j9k2m3n4p5q6r7/versions \
  -H "Authorization: Bearer lm_usr_your_key"
```

Response `200`:

```json
{
  "versions": [
    {
      "id": "ver_abc123",
      "version": "1.2.0",
      "status": "approved",
      "bundleSizeBytes": 182400,
      "submittedAt": "2026-04-01T08:00:00Z",
      "approvedAt": "2026-04-02T14:30:00Z"
    }
  ]
}
```

### Submit version

```
POST /extensions/:id/versions
```

Uploads a new version bundle. Use `multipart/form-data` with the compiled output directory as a `.tar.gz` archive.

```bash
curl -X POST https://api.lumio.vision/developer/v1/extensions/ext_01j9k2m3n4p5q6r7/versions \
  -H "Authorization: Bearer lm_usr_your_key" \
  -F "version=1.3.0" \
  -F "changelog=Fixed score display for overtime games." \
  -F "bundle=@dist/bundle.tar.gz"
```

Response `202 Accepted`:

```json
{
  "version": {
    "id": "ver_new_version_id",
    "version": "1.3.0",
    "status": "pending",
    "submittedAt": "2026-05-01T12:00:00Z"
  }
}
```

The `lumio deploy` CLI command wraps this endpoint.

---

## Installs

### List installs for an extension

```
GET /extensions/:id/installs
```

Returns aggregate install statistics. Individual user data is not exposed.

```bash
curl https://api.lumio.vision/developer/v1/extensions/ext_01j9k2m3n4p5q6r7/installs \
  -H "Authorization: Bearer lm_usr_your_key"
```

Response `200`:

```json
{
  "total": 142,
  "active": 138,
  "byVersion": {
    "ver_abc123": 130,
    "ver_older": 8
  }
}
```

---

## Secrets

### Set a secret

```
PUT /extensions/:id/secrets/:key
```

```bash
curl -X PUT https://api.lumio.vision/developer/v1/extensions/ext_01j9k2m3n4p5q6r7/secrets/API_KEY \
  -H "Authorization: Bearer lm_usr_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "value": "sk_live_abc123" }'
```

Response `204 No Content`.

### Delete a secret

```
DELETE /extensions/:id/secrets/:key
```

Response `204 No Content`.

### List secret keys

```
GET /extensions/:id/secrets
```

Returns key names only — values are never returned via the API.

```json
{ "keys": ["API_KEY", "WEBHOOK_SECRET"] }
```

---

## API Reference / SDK Client Reference

# SDK Client Reference

Complete reference for `@zaflun/lumio-sdk` — the client-side library used in `editor.tsx`, `layer.tsx`, and `interactive.tsx` surfaces.

## Import

```typescript
import { Lumio, Box, Text, useLumioEvent, useLumioConfig /* ... */ } from "@zaflun/lumio-sdk";
```

---

## Hooks

### useLumioConfig

Read and write the extension's configuration set by the editor panel.

```typescript
function useLumioConfig<T = Record<string, unknown>>(): {
  config: T | null;
  setConfig: (patch: Partial<T>) => Promise<void>;
  loading: boolean;
};
```

`setConfig` performs a shallow merge — only provided keys are updated. Available in all surfaces.

---

### useLumioEvent

Subscribe to a live stream event. Returns the latest event of the given type, or `null` before the first event.

```typescript
function useLumioEvent<T = unknown>(eventType: LumioEventType): LumioEvent<T> | null;
```

The hook reference changes every time a new event arrives. Use in a `useEffect` dependency array to respond to each event individually.

The `eventType` parameter is typed as `LumioEventType` — editors with TypeScript support provide autocomplete over all supported values. See the [`useLumioEvent` reference](/sdk/hooks/use-lumio-event) for the full list of 54 event types grouped by platform (Twitch, YouTube, Kick, Trovo, Spotify, StreamElements, and per-platform/catch-all chat events).

---

### useLumioAction

Call a server function defined in `server/functions.ts`.

```typescript
function useLumioAction(actionName: string): {
  invoke: (args: Record<string, unknown>) => Promise<unknown>;
  loading: boolean;
  error: Error | null;
};
```

`invoke` is stable across renders (memoized). `loading` is `true` while the server call is in flight.

---

### useExtensionStorage

Read and write key-based storage from the client side. Returns a tuple with the current value and a setter.

```typescript
function useExtensionStorage<T = Record<string, unknown>>(
  key: string,
  initialValue: T,
): [T, (value: T) => void];
```

On mount, the hook requests the current value from the host. External updates (from other instances or the host) are received automatically. Client-side storage access requires `"storage:read"` (and `"storage:write"` to write) in `permissions`.

---

### useLumioTheme

Returns the streamer's active overlay theme.

```typescript
function useLumioTheme(): LumioTheme;

interface LumioTheme {
  mode: "light" | "dark";
  primaryColor: string;        // hex color
  fontFamily: string;
  borderRadius: number;        // px
}
```

---

### useLumioIdentity

Returns the authenticated viewer's identity on the interactive page. Always `null` on `layer` and `editor`.

```typescript
function useLumioIdentity(): LumioIdentity | null;

interface LumioIdentity {
  userId: string;
  userName: string;
  platform: "twitch" | "youtube" | "kick" | "trovo" | null;
  platformUserId: string | null;
  isAuthenticated: boolean;
}
```

---

### useQuery

Declarative query hook — calls a server `query()` function and returns the result.

```typescript
function useQuery<T>(
  queryName: string,
  args: Record<string, unknown>,
  options?: { refetchInterval?: number }
): {
  data: T | null;
  loading: boolean;
  error: Error | null;
  refetch: () => Promise<void>;
};
```

`refetchInterval` polls on an interval (milliseconds). Use `useLumioAction` instead if you need imperative control.

---

### useMutation

Imperative mutation hook — wraps a server `action()` call with loading and error state.

```typescript
function useMutation<TArgs, TResult>(
  actionName: string
): {
  mutate: (args: TArgs) => Promise<TResult>;
  loading: boolean;
  error: Error | null;
  reset: () => void;
};
```

---

## Components

### Lumio.render

Entry point for mounting a surface.

```typescript
Lumio.render(element: React.ReactElement, options: { target: "layer" | "editor" | "interactive" }): void;
```

Must be called exactly once per surface file.

---

### Box

A general-purpose layout container. Renders a `<div>`.

```typescript
interface BoxProps {
  style?: React.CSSProperties;
  children?: React.ReactNode;
  onClick?: () => void;
  ref?: React.Ref<HTMLDivElement>;
  [key: string]: unknown; // data-* attributes passed through
}
```

---

### Text

Renders inline text with semantic variants.

```typescript
interface TextProps {
  content: string;
  variant?: "default" | "heading" | "muted" | "label" | "code";
  style?: React.CSSProperties;
}
```

---

### Image

Renders an image with automatic HTTPS enforcement and lazy loading.

```typescript
interface ImageProps {
  src: string;
  alt: string;
  style?: React.CSSProperties;
  onError?: () => void;
}
```

---

### Input

A text input field for use in the editor panel.

```typescript
interface InputProps {
  label?: string;
  value: string;
  onChange: (value: string) => void;
  placeholder?: string;
  type?: "text" | "email" | "url" | "password" | "number";
  disabled?: boolean;
}
```

---

### Select

A dropdown select field for use in the editor panel.

```typescript
interface SelectProps {
  label?: string;
  value: string;
  options: Array<{ value: string; label: string }>;
  onChange: (value: string) => void;
  disabled?: boolean;
}
```

---

### Toggle

A boolean toggle switch for use in the editor panel.

```typescript
interface ToggleProps {
  label: string;
  checked: boolean;
  onChange: (checked: boolean) => void;
  disabled?: boolean;
}
```

---

### Button

An interactive button for use in the editor panel or interactive page.

```typescript
interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: "primary" | "secondary" | "danger";
  loading?: boolean;
  disabled?: boolean;
  style?: React.CSSProperties;
}
```

---

## Animation utilities

### defineKeyframes

Registers a CSS keyframe animation and returns a unique name safe for use in `animation:` CSS properties.

```typescript
function defineKeyframes(frames: Record<string, React.CSSProperties>): string;
```

```typescript
const slideIn = defineKeyframes({
  from: { opacity: 0, transform: "translateY(-20px)" },
  to: { opacity: 1, transform: "translateY(0)" },
});

// Use in a Box style:
style={{ animation: `${slideIn} 0.4s ease forwards` }}
```

---

### localFont

Loads a font file bundled with the extension and returns a CSS `font-family` value.

```typescript
function localFont(options: { src: string; weight?: string; style?: string }): string;
```

```typescript
const myFont = localFont({ src: "./assets/CustomFont.woff2", weight: "400 700" });

<Box style={{ fontFamily: myFont }}>...</Box>
```

---

## API Reference / SDK Server Reference

# SDK Server Reference

Complete reference for `@zaflun/lumio-sdk/server` — the server-side library used in `server/functions.ts`.

## Import

```typescript
import { action, query, v } from "@zaflun/lumio-sdk/server";
```

---

## Defining functions

### action

Defines a server function that can be called by the client via `useLumioAction()` or `useMutation()`. Actions have full access to storage, secrets, egress, and real-time push.

```typescript
function action<TArgs, TReturn>(definition: {
  args: ArgSchema<TArgs>;
  handler: (ctx: ActionContext, args: TArgs) => Promise<TReturn>;
}): Action<TArgs, TReturn>;
```

```typescript
export const incrementScore = action({
  args: { amount: v.number() },
  handler: async (ctx, args) => {
    const current = (await ctx.db.get<number>("install", "score")) ?? 0;
    const next = current + args.amount;
    await ctx.db.set("install", "score", next);
    return { score: next };
  },
});
```

---

### query

Defines a read-only server function. Queries cannot write to storage, push real-time events, or call external APIs. They are intended for fetching state and may be cached by the platform.

```typescript
function query<TArgs, TReturn>(definition: {
  args: ArgSchema<TArgs>;
  handler: (ctx: QueryContext, args: TArgs) => Promise<TReturn>;
}): Query<TArgs, TReturn>;
```

```typescript
export const getScore = query({
  args: { userId: v.string() },
  handler: async (ctx, args) => {
    return ctx.db.get<number>("user", args.userId, "score") ?? 0;
  },
});
```

---

## ActionContext

The `ctx` parameter in `action()` handlers.

### ctx.db — Storage

Reads and writes extension storage, namespaced by scope.

```typescript
// Read a value
const value = await ctx.db.get<T>(scope, ...keys);

// Write a value
await ctx.db.set(scope, ...keys, value);

// Delete a value
await ctx.db.delete(scope, ...keys);

// List all keys in a scope (with optional prefix)
const keys = await ctx.db.list(scope, prefix?);
```

**Scopes:**

| Scope | Isolation | Capacity |
|-------|-----------|---------|
| `"global"` | Shared across all installs | 100 MB |
| `"install"` | Per overlay install | 10 MB |
| `"user"` | Per authenticated viewer (interactive page only) | 1 MB |

---

### ctx.fetch — External HTTP

Calls an external HTTPS endpoint. Subject to the `egress.allowHosts` allowlist declared in `lumio.config.json`.

```typescript
const res = await ctx.fetch("https://api.example.com/data");
const json = await res.json();
```

Has the same interface as the standard `fetch()` API. Restrictions:

- HTTPS only
- No private IP ranges or localhost
- Maximum 10 calls per action invocation
- 30-second timeout per request

---

### ctx.secrets — Secret access

Reads secrets stored via `lumio secrets set` or the dashboard.

```typescript
const apiKey = ctx.secrets.get("MY_API_KEY");   // throws if not set
const exists = ctx.secrets.has("MY_API_KEY");    // boolean check
```

Secret values are never logged or returned to the client.

---

### ctx.realtime — Push real-time events

Pushes an event to all connected surfaces (layer, editor, interactive page) for this install.

```typescript
await ctx.realtime.push("score:updated", { score: 42 });
```

Clients receive the event via a WebSocket subscription. Listen with:

```typescript
window.addEventListener("lumio:realtime", (event) => {
  if (event.type === "score:updated") {
    console.log(event.data.score);
  }
});
```

Maximum 64 KB payload. Maximum 100 pushes/second per extension.

---

### ctx.cache — Scoped cache

Scoped Redis key-value cache. Faster than `ctx.db` for temporary data that can be lost.

```typescript
await ctx.cache.set("counter", 42, 3600);       // set with TTL in seconds
const val = await ctx.cache.get("counter");      // get value
await ctx.cache.increment("counter", 1);         // atomic increment
await ctx.cache.delete("counter");               // delete key
```

Keys are scoped per install (`ext-cache:{install_id}:*`). TTL range 1s–24h, default 1h. See [Cache & Background Jobs](/guides/cache-and-defer).

---

### ctx.defer — Background work

Queue a function to run after the handler returns — useful for background DB writes after a fast cache read.

```typescript
ctx.defer(async () => {
  await ctx.db.set("install", "last_run", Date.now());
});
```

Max 5 deferred calls per handler invocation. Each has a 10s timeout. See [Cache & Background Jobs](/guides/cache-and-defer).

---

### ctx.identity — Caller identity

Present when the action is called from the interactive page by an authenticated viewer. `null` on the layer and editor surfaces.

```typescript
if (ctx.identity) {
  console.log(ctx.identity.userId);
  console.log(ctx.identity.platform);       // "twitch" | "youtube" | ...
  console.log(ctx.identity.platformUserId);
}
```

---

## QueryContext

The `ctx` parameter in `query()` handlers. A subset of `ActionContext` — read-only access only.

| Property | Available |
|----------|----------|
| `ctx.db.get` | Yes |
| `ctx.db.list` | Yes |
| `ctx.db.set` | No — throws |
| `ctx.fetch` | No — throws |
| `ctx.secrets` | Yes (read-only) |
| `ctx.realtime` | No — throws |
| `ctx.identity` | Yes |

---

## Validation — `v`

The `v` object provides runtime argument validators. All args must be declared with `v` — undeclared fields are stripped before the handler runs.

```typescript
// Primitives
v.string()
v.number()
v.boolean()
v.null_()

// Modifiers
v.optional(v.string())        // string | undefined — field may be absent
v.nullable(v.string())        // string | null

// Collections
v.array(v.string())
v.object({ name: v.string(), count: v.number() })

// Union
v.union([v.string(), v.number()])

// Literal
v.literal("active")
```

Validation happens before the handler is called. Invalid args return a structured error to the caller without invoking the handler.

---

## Exports from `server/functions.ts`

Every named export from `server/functions.ts` that is an `action()` or `query()` result is automatically registered with the platform at deploy time. No additional registration step is needed.

```typescript
// server/functions.ts
export const getScore = query({ ... });     // registered as "getScore"
export const setScore = action({ ... });    // registered as "setScore"

// Not registered — not an action or query
export const MULTIPLIER = 2;
```

The exported name becomes the `actionName` / `queryName` used on the client.

---

## Bot module handlers

Bot module extensions (`category: "bot_module"`) use a separate set of handler wrappers for chat interaction. Each wrapper sets a `__type` discriminant on the exported function, following the same pattern as `query()` and `action()`.

### Handler type reference

| Wrapper | `__type` | `__trigger` | Sync/Async | Timeout |
|---------|----------|-------------|------------|---------|
| `command(name, handler)` | `"command"` | Command name | Sync | 500ms |
| `keyword(word, handler)` | `"keyword"` | Keyword string | Async | 10s |
| `pattern(regex, handler)` | `"pattern"` | Regex string | Async | 10s |
| `event(type, handler)` | `"event"` | Event type | Async | 10s |
| `timer(name, handler)` | `"timer"` | Timer name | Async | 10s |
| `moderate(handler)` | `"moderate"` | N/A | Sync | 500ms |

### Signatures

```typescript
function command(
  name: string,
  handler: (ctx: BotModuleContext, args: string[]) => Promise<HandlerResponse | null>
): CommandDefinition;

function keyword(
  word: string,
  handler: (ctx: BotModuleContext, message: ChatMessage) => Promise<HandlerResponse | null>
): KeywordDefinition;

function pattern(
  regex: string,
  handler: (ctx: BotModuleContext, message: ChatMessage, matched: string) => Promise<HandlerResponse | null>
): PatternDefinition;

function event(
  eventType: string,
  handler: (ctx: BotModuleContext, evt: Record<string, unknown>) => Promise<HandlerResponse | null>
): EventDefinition;

function timer(
  name: string,
  handler: (ctx: BotModuleContext) => Promise<HandlerResponse | null>
): TimerDefinition;

function moderate(
  handler: (ctx: BotModuleContext, message: ChatMessage) => Promise<ModerationResponse>
): ModerateDefinition;
```

### BotModuleContext

See [Bot Module Context](/sdk/hooks/bot-module-context) for the full API reference.

### HandlerResponse

```typescript
interface HandlerResponse {
  reply?: string;
  actions?: ActionRequest[];
}

interface ActionRequest {
  action: string;
  params: Record<string, unknown>;
}
```

### ModerationResponse

```typescript
interface ModerationResponse {
  block: boolean;
  action?: "delete" | "timeout" | "ban";
  duration?: number;
  reason?: string;
}
```

### ChatMessage

```typescript
interface ChatMessage {
  text: string;
  platformMessageId: string;
}
```

---

## API Reference / CLI Reference

# CLI Reference

Quick-reference table and flag reference for the `lumio` CLI.

## Installation

```bash
npm install -g @zaflun/lumio-cli
# or
pnpm add -g @zaflun/lumio-cli
```

## Commands

| Command | Description |
|---------|-------------|
| `lumio login` | Authenticate to your developer account |
| `lumio logout` | Remove stored credentials |
| `lumio init` | Scaffold a new extension |
| `lumio dev` | Start local development server |
| `lumio build` | Build for production |
| `lumio deploy` | Deploy a new version |
| `lumio status` | Show extension status |
| `lumio logs` | Stream server function logs |
| `lumio secrets set <KEY> <VALUE>` | Store a secret |
| `lumio secrets delete <KEY>` | Delete a secret |
| `lumio secrets list` | List secret key names |

---

## lumio login

```
lumio login [--token <api_key>]
```

Without `--token`, opens a browser-based OAuth flow. With `--token`, uses the provided API key directly (useful in CI).

| Flag | Description |
|------|-------------|
| `--token <key>` | Authenticate with an API key instead of browser flow |

---

## lumio init

```
lumio init [name] [--template <template>]
```

| Flag | Description |
|------|-------------|
| `--template <name>` | Scaffold from a template: `blank`, `alert`, `scoreboard`, `poll`, `chat` |
| `--dir <path>` | Directory to create the project in (default: `./<name>`) |

---

## lumio dev

```
lumio dev [--port <port>] [--no-open]
```

Starts a local development server with hot module replacement. Opens the preview URL in the browser automatically.

| Flag | Description |
|------|-------------|
| `--port <n>` | HTTP port for the dev server (default: `3010`) |
| `--no-open` | Do not open the browser automatically |
| `--mock <file>` | Load a mock events file for simulating stream events |

The dev server injects a mock Lumio runtime so `useLumioEvent`, `useLumioConfig`, and `useLumioAction` all work without a real connected overlay.

---

## lumio build

```
lumio build [--outdir <path>]
```

Compiles and bundles all surfaces for production. Output goes to `dist/` by default.

| Flag | Description |
|------|-------------|
| `--outdir <path>` | Output directory (default: `dist`) |
| `--analyze` | Print bundle size breakdown after build |

Build fails if:
- A surface bundle exceeds 5 MB (gzipped)
- TypeScript type errors are present
- `lumio.config.json` fails schema validation

---

## lumio deploy

```
lumio deploy [--version <semver>] [--changelog <text>] [--dry-run]
```

Builds the extension and submits it as a new version for review. Equivalent to `lumio build` followed by `POST /extensions/:id/versions`.

| Flag | Description |
|------|-------------|
| `--version <semver>` | Override version from `lumio.config.json` |
| `--changelog <text>` | Short changelog for this version |
| `--dry-run` | Build and validate but do not upload |
| `--no-build` | Skip the build step (use existing `dist/`) |

After deploying, the version enters `pending` status and awaits review.

---

## lumio status

```
lumio status [extension-id]
```

Prints the current extension status, latest version, install count, and pending review details.

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON |

---

## lumio logs

```
lumio logs [--tail] [--since <duration>] [--level <level>]
```

Streams server function logs to stdout. Requires the extension to have server functions enabled.

| Flag | Description |
|------|-------------|
| `--tail` | Follow new logs in real time (default: true) |
| `--no-tail` | Print recent logs and exit |
| `--since <duration>` | Show logs from the past duration, e.g. `1h`, `30m`, `7d` |
| `--level <level>` | Filter by log level: `debug`, `info`, `warn`, `error` |
| `--json` | Raw JSON log output |

---

## lumio secrets

```
lumio secrets set <KEY> <VALUE>
lumio secrets delete <KEY>
lumio secrets list
```

Manages secrets stored in Lumio Vault for your extension. Secrets are available in server functions via `ctx.secrets.get()`.

| Subcommand | Description |
|-----------|-------------|
| `set <KEY> <VALUE>` | Create or update a secret |
| `delete <KEY>` | Delete a secret |
| `list` | List key names (values are never shown) |

Secret keys must match `[A-Z][A-Z0-9_]*` (uppercase, starting with a letter).

---

## Environment variables

| Variable | Description |
|----------|-------------|
| `LUMIO_API_KEY` | API key — overrides stored credentials |
| `LUMIO_EXTENSION_ID` | Extension ID — overrides `lumio.config.json` |
| `LUMIO_API_URL` | Override the API base URL (for self-hosted / staging) |
| `NO_COLOR` | Disable colored output |

---

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | General error (see stderr) |
| `2` | Authentication error |
| `3` | Validation error (config or bundle) |
| `4` | Network error / API unreachable |
| `5` | Rate limit exceeded |

---

## API Reference / TypeScript Types

# TypeScript Types

Complete TypeScript type reference for the Lumio Developer SDK and Developer REST API.

## Core extension types

### Extension

Represents a published extension in the Lumio store.

```typescript
interface Extension {
  id: string;                  // "ext_01j9k2m3n4p5q6r7s8t9u0v1w2"
  slug: string;                // "my-scoreboard"
  name: string;
  description: string;
  shortDescription: string;
  authorId: string;
  visibility: "private" | "unlisted" | "public";
  status: "draft" | "in_review" | "approved" | "rejected" | "suspended";
  pricing: PricingConfig;
  currentVersionId: string | null;
  installCount: number;
  rating: number | null;
  ratingCount: number;
  createdAt: string;           // ISO 8601
  updatedAt: string;
}
```

### ExtensionVersion

A specific published version of an extension.

```typescript
interface ExtensionVersion {
  id: string;
  extensionId: string;
  version: string;             // semver, e.g. "1.2.0"
  changelog: string;
  status: "pending" | "approved" | "rejected";
  targets: ExtensionTarget[];
  hasServer: boolean;
  bundleSizeBytes: number;
  submittedAt: string;
  approvedAt: string | null;
}

type ExtensionTarget = "layer" | "editor" | "interactive";
```

### ExtensionInstall

A record of an extension installed in a user's Lumio account.

```typescript
interface ExtensionInstall {
  id: string;                  // installId
  extensionId: string;
  extensionVersionId: string;
  accountId: string;
  overlayId: string | null;    // null if not yet placed on an overlay
  config: Record<string, unknown>;
  installedAt: string;
  updatedAt: string;
}
```

### PricingConfig

```typescript
type PricingConfig =
  | { type: "free" }
  | { type: "one_time"; amount: number; currency: "EUR" | "USD" | "GBP" }
  | {
      type: "subscription";
      amount: number;
      currency: "EUR" | "USD" | "GBP";
      interval: "monthly";
    };
```

## Config types

### LumioConfig

The shape returned by `useLumioConfig()`. The `config` field is the raw JSON stored by the editor.

```typescript
interface UseLumioConfigResult<T = Record<string, unknown>> {
  config: T | null;
  setConfig: (patch: Partial<T>) => Promise<void>;
  loading: boolean;
}
```

### LumioConfigSchema

A field descriptor used in the declarative `defineConfig()` API.

```typescript
type LumioConfigField =
  | { type: "string"; label: string; default?: string; placeholder?: string }
  | { type: "number"; label: string; default?: number; min?: number; max?: number }
  | { type: "boolean"; label: string; default?: boolean }
  | { type: "select"; label: string; options: Array<{ value: string; label: string }>; default?: string }
  | { type: "color"; label: string; default?: string };
```

## Event types

### LumioEvent

```typescript
interface LumioEvent<T = unknown> {
  type: LumioEventType;
  timestamp: string;           // ISO 8601
  data: T;
}

type LumioEventType =
  // Twitch
  | "twitch:follower"
  | "twitch:subscribe"
  | "twitch:gift_sub"
  | "twitch:resub"
  | "twitch:cheer"
  | "twitch:raid"
  | "twitch:reward"
  | "twitch:hype_train"
  | "twitch:hype_train_end"
  | "twitch:poll"
  | "twitch:poll_end"
  | "twitch:prediction"
  | "twitch:prediction_lock"
  | "twitch:prediction_end"
  | "twitch:goal"
  | "twitch:goal_end"
  | "twitch:ad_break"
  | "twitch:ban"
  | "twitch:unban"
  | "twitch:stream_online"
  | "twitch:stream_offline"
  | "twitch:stream_update"
  // YouTube
  | "youtube:subscribe"
  | "youtube:member"
  | "youtube:superchat"
  | "youtube:supersticker"
  | "youtube:gift_membership"
  | "youtube:gift_membership_received"
  | "youtube:poll"
  // Kick
  | "kick:follower"
  | "kick:subscribe"
  | "kick:gift"
  | "kick:stream_online"
  | "kick:stream_offline"
  | "kick:chat"
  // Trovo
  | "trovo:subscribe"
  | "trovo:spell"
  | "trovo:chat"
  // Spotify
  | "spotify:track"
  | "spotify:play"
  | "spotify:pause"
  | "spotify:skip"
  | "spotify:volume"
  | "spotify:queue_add"
  | "spotify:device"
  | "spotify:playlist_add"
  | "spotify:playlist_remove"
  | "spotify:playlist_create"
  | "spotify:playlist_edit"
  | "spotify:playlist_delete"
  // StreamElements
  | "streamelements:tip"
  // Chat — per-platform
  | "twitch:chat"
  | "youtube:chat"
  // Chat — catch-all (fires for all platforms)
  | "chat:message";
```

### Event payload types

```typescript
interface TwitchFollowerData {
  userName: string;
  userId: string;
  followedAt: string;
}

interface TwitchSubscribeData {
  userName: string;
  userId: string;
  tier: "1000" | "2000" | "3000" | "prime";
  months: number;
  message: string | null;
}

interface TwitchGiftSubData {
  gifterName: string;
  gifterUserId: string;
  recipientName: string;
  recipientUserId: string;
  tier: "1000" | "2000" | "3000";
}

interface TwitchResubData {
  userName: string;
  userId: string;
  tier: "1000" | "2000" | "3000" | "prime";
  months: number;
  message: string | null;
}

interface TwitchCheerData {
  userName: string;
  userId: string;
  bits: number;
  message: string;
}

interface TwitchRaidData {
  fromBroadcasterName: string;
  fromBroadcasterId: string;
  viewerCount: number;
}

interface TwitchRewardData {
  userName: string;
  userId: string;
  rewardId: string;
  rewardTitle: string;
  rewardCost: number;
  input: string | null;
  status: "unfulfilled" | "fulfilled" | "canceled";
}

interface TwitchBanData {
  userName: string;
  userId: string;
  reason: string | null;
  moderatorName: string;
}

interface TwitchUnbanData {
  userName: string;
  userId: string;
  moderatorName: string;
}

interface TwitchStreamOnlineData {
  broadcasterName: string;
  broadcasterId: string;
  startedAt: string;
}

interface TwitchStreamOfflineData {
  broadcasterName: string;
  broadcasterId: string;
}

interface TwitchStreamUpdateData {
  title: string;
  categoryName: string;
  categoryId: string;
}

interface SpotifyTrackData {
  title: string;
  artist: string;
  album: string;
  albumArtUrl: string;
  duration: number;            // milliseconds
  progress: number;            // milliseconds
  isPlaying: boolean;
}

interface ChatMessageData {
  platform: "twitch" | "youtube" | "kick" | "trovo";
  userName: string;
  userId: string;
  message: string;
  emotes: Array<{ id: string; name: string; url: string }>;
  badges: string[];
  color?: string;
}
```

## Server function types

### ActionHandler

```typescript
type ActionHandler<TArgs, TReturn> = (
  ctx: ActionContext,
  args: TArgs
) => Promise<TReturn>;

interface ActionContext {
  db: StorageContext;
  fetch: typeof fetch;
  secrets: SecretsContext;
  realtime: RealtimeContext;
  identity: IdentityContext | null;
}
```

### StorageContext

```typescript
interface StorageContext {
  get<T>(scope: "global" | "install" | "user", key: string): Promise<T | null>;
  get<T>(scope: "global" | "install" | "user", ...keys: string[]): Promise<T | null>;
  set(scope: "global" | "install" | "user", key: string, value: unknown): Promise<void>;
  set(scope: "global" | "install" | "user", ...keysAndValue: [...string[], unknown]): Promise<void>;
  delete(scope: "global" | "install" | "user", ...keys: string[]): Promise<void>;
  list(scope: "global" | "install" | "user", prefix?: string): Promise<string[]>;
}
```

### SecretsContext

```typescript
interface SecretsContext {
  get(key: string): string;    // throws if key not set
  has(key: string): boolean;
}
```

### RealtimeContext

```typescript
interface RealtimeContext {
  push(event: string, data: unknown): Promise<void>;
}
```

## Theme types

```typescript
interface LumioTheme {
  mode: "light" | "dark";
  primaryColor: string;        // hex, e.g. "#6366f1"
  fontFamily: string;
  borderRadius: number;        // px
}
```

## Identity types

```typescript
interface LumioIdentity {
  userId: string;
  userName: string;
  platform: "twitch" | "youtube" | "kick" | "trovo" | null;
  platformUserId: string | null;
  isAuthenticated: boolean;
}
```

## Validation schema types

```typescript
import { v } from "@zaflun/lumio-sdk/server";

// Primitive validators
v.string()                    // string
v.number()                    // number
v.boolean()                   // boolean
v.null_()                     // null

// Compound validators
v.optional(v.string())        // string | undefined
v.nullable(v.string())        // string | null
v.array(v.string())           // string[]
v.object({ key: v.string() }) // { key: string }
v.union([v.string(), v.number()]) // string | number
v.literal("exact")            // "exact"
```

---

## Guides / Debugging

# Debugging

This guide covers common debugging techniques for Lumio extension development, from local dev server issues to production server function errors.

## Extension Developer Mode

Enable **Extension Developer Mode** in the widget or overlay editor via **Settings → Extension Developer Mode**. When active:

- Extension bundle serving loads the **latest draft or testing version** instead of the published version for extensions you develop
- A **Debug Panel** (floating window) opens automatically with tabs for Events, Storage, Messages, and Console output
- A toast notification confirms activation: *"Developer mode enabled — extensions will use dev versions"*

This lets you test draft versions directly in the editor without publishing. Toggle it off to return to the published version.

The setting is stored on your user account (`extension_dev_mode`) and persists across sessions. It only affects extensions where you are a team member/developer — other extensions always load the published version.

## Local development

### Dev server logs

When `lumio dev` is running, logs from server functions are printed directly to the terminal. Look for lines prefixed with `[server]`:

```
[server] INFO  getScoreboard called with { sport: "basketball", league: "nba" }
[server] ERROR getScoreboard failed: ESPN API error: 429
```

Add `console.log()` statements in your handler freely during development — they appear in the terminal and are stripped from the production build.

### Inspecting the overlay preview

The dev server opens a preview at `http://localhost:3010/preview`. This page renders the `layer` surface inside a 1920×1080 canvas. Open your browser's DevTools (F12) to:

- Inspect the React component tree
- Check the console for SDK errors
- Profile render performance

The editor panel is at `http://localhost:3010/editor` and the interactive page at `http://localhost:3010/interactive`.

### Simulating events

Use `--mock` to load a mock events file:

```bash
lumio dev --mock ./mocks/events.json
```

The events file is an array of event objects:

```json
[
  {
    "type": "twitch:follower",
    "timestamp": "2026-05-01T10:00:00Z",
    "data": { "userName": "testuser", "userId": "u_001", "followedAt": "2026-05-01T10:00:00Z" }
  },
  {
    "type": "spotify:track",
    "timestamp": "2026-05-01T10:01:00Z",
    "data": {
      "title": "Test Track",
      "artist": "Test Artist",
      "album": "Test Album",
      "albumArtUrl": "https://i.scdn.co/image/placeholder",
      "duration": 210000,
      "progress": 45000,
      "isPlaying": true
    }
  }
]
```

In the preview UI, click **Send Event** to dispatch the next event from the file.

---

## Debugging server functions

### Checking logs in production

Stream production logs with:

```bash
lumio logs --tail
```

Filter by error level:

```bash
lumio logs --level error --since 1h
```

### Common server function errors

**`"Host not in allowHosts"`**

You called `ctx.fetch()` with a host not listed in `egress.allowHosts`. Add the host to `lumio.config.json`:

```json
{
  "egress": {
    "allowHosts": ["api.example.com"]
  }
}
```

**`"Secret key not found: MY_KEY"`**

The secret hasn't been set for this extension. Run:

```bash
lumio secrets set MY_KEY "your_value_here"
```

**`"Action invocation timeout"`**

The handler took longer than 30 seconds. Check for:
- Slow external API calls — add a timeout to `ctx.fetch()`
- Unbounded loops in the handler
- Large storage reads/writes

```typescript
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 8_000);
const res = await ctx.fetch("https://slow-api.example.com/data", {
  signal: controller.signal,
});
clearTimeout(timeout);
```

**`"Storage key size exceeded"`**

The value you tried to store is larger than 64 KB. Compress or split the data across multiple keys.

---

## React component debugging

### Unexpected re-renders

If your layer re-renders too frequently, check:

1. **`useLumioEvent` in a dependency array** — the event reference changes on every new event. If your `useEffect` depends on the event, it runs on every event. That is the intended behavior.

2. **Object/array literals in `style` props** — create style objects outside the component or use `useMemo`:

```tsx
// Bad — new object on every render
<Box style={{ color: "red", padding: 8 }}>

// Good — stable reference
const containerStyle: React.CSSProperties = { color: "red", padding: 8 };
<Box style={containerStyle}>
```

3. **`setConfig` in a loop** — `setConfig` triggers a re-render and a network call. Batch updates:

```tsx
// Bad
await setConfig({ a: 1 });
await setConfig({ b: 2 });

// Good
await setConfig({ a: 1, b: 2 });
```

### White screen / nothing renders

1. Check the browser console for JavaScript errors
2. Make sure `Lumio.render()` is called at the module level, not inside a React component
3. Verify the `target` in `Lumio.render()` matches the URL you're previewing (`layer`, `editor`, or `interactive`)

---

## Build errors

### TypeScript errors

Run the TypeScript compiler to see all type errors at once:

```bash
cd my-extension && npx tsc --noEmit
```

### Bundle too large

Run `lumio build --analyze` to see which modules contribute to the bundle size. Common culprits:

- Importing entire icon libraries — import individual icons instead
- Importing large utility libraries — check if a smaller alternative exists
- Embedding image data as base64 — use external URLs or the static assets folder instead

### MDX / JSX syntax error in docs

Not applicable to extensions, but if you're editing `apps/developer-docs/docs/`, remember that `{placeholder}` in MDX headings must be escaped as `{placeholder}` outside code fences.

---

## Guides / Testing Extensions

# Testing Extensions

Lumio extensions are React applications with server functions. This guide covers unit testing components, testing server functions, and manual testing against a real overlay before submitting for review.

## Testing strategy

| Level | What to test | Tool |
|-------|-------------|------|
| Unit | Pure functions, validators, data transforms | Vitest or Jest |
| Component | Rendering logic, UI state, config reads | React Testing Library |
| Integration | Server function handlers with mocked storage | Vitest + hand-rolled mocks |
| Manual (local) | Full flow: editor → layer → events | `lumio dev` |
| Manual (staging) | Live overlay in browser source with real events | `lumio deploy` to staging |

---

## Setting up Vitest

```bash
pnpm add -D vitest @testing-library/react @testing-library/user-event jsdom
```

`vitest.config.ts`:

```typescript
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    environment: "jsdom",
    globals: true,
  },
});
```

`package.json`:

```json
{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest"
  }
}
```

---

## Testing server function handlers

Server functions are plain async functions — test the `handler` directly by constructing a minimal `ctx` mock.

```typescript
// server/functions.test.ts
import { describe, it, expect, vi } from "vitest";
import { incrementScore } from "./functions";

function makeCtx(storage: Record<string, unknown> = {}) {
  return {
    db: {
      get: vi.fn(async (_scope, ...keys) => storage[keys.join("/")] ?? null),
      set: vi.fn(async (_scope, ...keysAndValue) => {
        const value = keysAndValue[keysAndValue.length - 1];
        const keys = (keysAndValue.slice(0, -1) as string[]).join("/");
        storage[keys] = value;
      }),
      delete: vi.fn(),
      list: vi.fn(async () => []),
    },
    fetch: vi.fn(),
    secrets: { get: vi.fn((k: string) => `mock_${k}`), has: vi.fn(() => true) },
    realtime: { push: vi.fn() },
    identity: null,
  };
}

describe("incrementScore", () => {
  it("starts at 0 and increments", async () => {
    const ctx = makeCtx();
    const result = await incrementScore.handler(ctx, { amount: 5 });
    expect(result.score).toBe(5);
  });

  it("adds to existing score", async () => {
    const ctx = makeCtx({ score: 10 });
    const result = await incrementScore.handler(ctx, { amount: 3 });
    expect(result.score).toBe(13);
  });

  it("pushes a realtime event", async () => {
    const ctx = makeCtx();
    await incrementScore.handler(ctx, { amount: 1 });
    expect(ctx.realtime.push).toHaveBeenCalledWith("score:updated", { score: 1 });
  });
});
```

---

## Testing React components

Use React Testing Library to render surfaces and assert on output.

```typescript
// src/layer.test.tsx
import { describe, it, expect, vi } from "vitest";
import { render, screen } from "@testing-library/react";
import { ScoreDisplay } from "./layer";

// Mock the SDK hooks
vi.mock("@zaflun/lumio-sdk", () => ({
  useLumioConfig: () => ({
    config: { homeTeam: "LAL", awayTeam: "BOS" },
    setConfig: vi.fn(),
    loading: false,
  }),
  useLumioTheme: () => ({ mode: "dark", primaryColor: "#6366f1", fontFamily: "sans-serif", borderRadius: 8 }),
  useLumioEvent: () => null,
  Box: ({ children, ...props }: React.HTMLAttributes<HTMLDivElement>) => <div {...props}>{children}</div>,
  Text: ({ content }: { content: string }) => <span>{content}</span>,
}));

describe("ScoreDisplay", () => {
  it("renders team names from config", () => {
    render(<ScoreDisplay />);
    expect(screen.getByText("LAL")).toBeInTheDocument();
    expect(screen.getByText("BOS")).toBeInTheDocument();
  });
});
```

---

## Manual testing checklist

Before submitting for review, work through this checklist using `lumio dev`:

### Editor panel

- [ ] All config fields render correctly
- [ ] Changing a setting immediately updates the layer (no page reload needed)
- [ ] Default values display when config is empty
- [ ] Text inputs accept long strings without layout breakage
- [ ] Required fields show a validation hint if empty

### Layer

- [ ] Renders correctly at 1920×1080
- [ ] Renders correctly at 1280×720 (test by resizing the preview browser window)
- [ ] Transparent backgrounds are truly transparent (check against a non-black background)
- [ ] Fonts load correctly (no fallback to system font)
- [ ] Animations play at smooth 60 fps

### Event handling

- [ ] Displays correctly when no event has arrived yet (null state)
- [ ] Responds to the first event within 1 second
- [ ] Handles rapid events without visual glitches or memory leaks
- [ ] Auto-dismiss timers work correctly

### Interactive page

- [ ] Renders on mobile screen sizes (375px wide)
- [ ] Unauthenticated users see an appropriate message or login prompt
- [ ] All user interactions are reflected on the layer within 500ms

### Server functions

- [ ] Actions return expected results
- [ ] Error conditions are handled gracefully (no unhandled promise rejections in the console)
- [ ] External API failures show a user-friendly fallback

---

## Staging deployment

Deploy to staging to test with real Twitch/YouTube events before submitting:

```bash
lumio deploy --version 0.9.0-rc1 --changelog "Release candidate for testing"
```

Install the extension on a test overlay and go live on Twitch. Trigger real events (follow, subscribe, chat) to verify end-to-end behavior.

Check production logs while testing:

```bash
lumio logs --tail --level info
```

---

## Guides / Migration Guide

# Migration Guide

This page documents breaking changes between SDK major versions and the steps to migrate existing extensions.

## Current version

The current SDK major version is **v1**. This is the initial stable release. No migrations are required for extensions created with `@zaflun/lumio-sdk@^1.0.0`.

## Future migrations

When a new major version is released, this page will be updated with:

- The full list of breaking changes
- Automated codemod scripts where available
- Step-by-step manual migration instructions
- A migration deadline (how long the previous version will continue to receive bug fixes)

## Staying current

Watch the [`@zaflun/lumio-sdk` release history on npm](https://www.npmjs.com/package/@zaflun/lumio-sdk?activeTab=versions) to be notified when new versions are published.

The `lumio status` CLI command also shows whether your extension's SDK version is current:

```bash
lumio status
```

```
Extension: Sports Scoreboard (ext_01j9k2m3n4p5q6r7)
Status:    approved
Version:   1.2.0
SDK:       @zaflun/lumio-sdk@1.0.0  ✓  (latest)
```

## Deprecation policy

Before any breaking change is shipped:

1. The deprecated API is marked in the TypeScript types with a `@deprecated` JSDoc tag
2. The runtime emits a `console.warn` when the deprecated API is used in dev mode
3. A migration guide entry is published at least 3 months before removal
4. The CLI prints a warning during `lumio build` if deprecated APIs are detected

## Reporting compatibility issues

If you find that an SDK update broke your extension in an undocumented way, file a bug report in the developer portal with:

- Your SDK version (`package.json` → `@zaflun/lumio-sdk`)
- The previous SDK version where it worked
- A minimal reproduction case

We treat unannounced breaking changes as bugs and aim to fix them within 48 hours.

---

## Guides / Best Practices

# Best Practices

Guidelines for building reliable, performant, and review-friendly Lumio extensions.

## Performance

### Keep bundle sizes small

Browser Sources have limited memory. Aim for bundles under 1 MB gzipped.

- Import only what you use: `import { Box, Text } from "@zaflun/lumio-sdk"` not `import * as SDK from "@zaflun/lumio-sdk"`
- Avoid lodash, moment.js, and other large utility libraries — use native browser APIs
- Prefer `<Image>` over inline base64 data URIs for assets larger than 1 KB
- Run `lumio build --analyze` to identify large dependencies

### Minimize re-renders on the layer

The layer runs in an Browser Source at 60 fps. Expensive renders cause dropped frames.

- Memoize computed values with `useMemo`
- Memoize callbacks with `useCallback` when passing them to child components
- Keep component state as local as possible — avoid a single top-level state object for everything
- Use `React.memo` on pure display components that receive stable props

### Limit event-driven updates

`useLumioEvent` triggers a re-render on every event. If you only need the data after an event (not reactive to each one), debounce or queue events in a ref:

```tsx
const lastEventRef = useRef<LumioEvent | null>(null);
const event = useLumioEvent("twitch:cheer");

useEffect(() => {
  if (event === lastEventRef.current) return; // Already processed
  lastEventRef.current = event;
  // Handle event...
}, [event]);
```

---

## Reliability

### Handle the null state

`useLumioEvent` returns `null` before the first event. `useLumioConfig` returns `null` while loading. Always handle these:

```tsx
const event = useLumioEvent("twitch:follower");
const { config, loading } = useLumioConfig<MyConfig>();

if (loading) return null;              // or a skeleton
if (!config) return null;              // not configured yet
if (!event) return <DefaultState />;   // waiting for first event
```

### Never store secrets in client code

Secrets (API keys, webhook secrets) must live in `lumio secrets`, not in the extension bundle or `lumio.config.json`. A user can inspect the bundle at any time.

### Validate server function inputs

Even though `v` validators strip unknown fields, add semantic validation in your handler:

```typescript
handler: async (ctx, args) => {
  if (args.amount <= 0 || args.amount > 1000) {
    throw new Error("Amount must be between 1 and 1000");
  }
  // ...
}
```

### Handle external API failures gracefully

External APIs can be slow or unavailable. Always have a fallback:

```typescript
handler: async (ctx, args) => {
  try {
    const res = await ctx.fetch("https://api.example.com/data");
    return await res.json();
  } catch {
    // Return cached data if available
    return await ctx.db.get("global", "last_known_data") ?? { empty: true };
  }
}
```

---

## User experience

### Design for 1920×1080 first

Most streamers run at 1080p. Test at 1080p first, then check at 720p. Avoid fixed pixel positions that break at different canvas sizes — use percentage or anchor-based positioning instead.

### Respect the overlay canvas

Overlays sit on top of game footage or IRL video. Keep the overlay visually lightweight:

- Prefer semi-transparent backgrounds over solid fills
- Avoid covering more than 20% of the canvas area
- Ensure text is readable against both light and dark backgrounds

### Support the streamer's theme

Use `useLumioTheme()` to adapt colors to the streamer's chosen theme instead of hardcoding colors. At minimum, use the `mode` field to choose light/dark variants:

```tsx
const theme = useLumioTheme();
const bg = theme.mode === "dark" ? "rgba(0,0,0,0.7)" : "rgba(255,255,255,0.8)";
```

### Provide sensible defaults

Every config field should have a default so the extension works out of the box before the streamer visits the editor:

```tsx
const { config } = useLumioConfig<MyConfig>();
const position = config?.position ?? "top-right";
const fontSize = config?.fontSize ?? 14;
```

---

## Review readiness

These practices help your extension pass review faster.

### Match egress to purpose

Only list hosts in `allowHosts` that your extension actually calls, and ensure each one is clearly related to the extension's stated purpose. Reviewers reject extensions with overly broad or unexplained egress hosts.

### Write a clear store listing

The review team reads your store description. Explain what the extension does, what permissions it needs and why, and what data it stores. Vague descriptions cause review delays.

### Test before submitting

Run through the [testing checklist](/guides/testing#manual-testing-checklist) before every submission. Extensions that crash or display a blank screen in testing are rejected without deeper review.

### Use semantic versioning

Follow semver for version strings: `MAJOR.MINOR.PATCH`. Increment `MAJOR` for breaking config changes that require re-configuring the editor panel. Increment `MINOR` for new features. Increment `PATCH` for bug fixes.

### Write meaningful changelogs

The changelog is shown to users when they update the extension. Write what changed from the user's perspective, not internal implementation notes:

```
# Good
Fixed score display not updating during overtime periods.
Added support for displaying 3-point shooting percentage.

# Bad
Refactored ESPN fetch handler. Fixed off-by-one in state reducer.
```

---

## Guides / Sandbox Architecture

# Sandbox Architecture

Lumio runs every extension inside a multi-layer sandbox. Understanding the sandbox helps you reason about what extensions can and cannot do, and makes debugging straightforward when something unexpected happens.

## Why sandboxing matters

Extensions are third-party code executed inside the viewer's browser and Lumio's servers. Without isolation, a malicious or buggy extension could:

- Read or write another extension's storage
- Send arbitrary network requests using the viewer's session
- Crash or freeze the host overlay page
- Access sensitive viewer data (tokens, cookies, clipboard)

The Lumio sandbox prevents all of the above at the architecture level rather than relying on code review alone.

## 3-Layer architecture

```
Host (lumio.vision)
  └─ Supervisor iframe  (supervisor.ext.lumio.vision)
       └─ Extension Runtime iframe  (ext.lumio.vision)
            └─ Web Worker  (lumio-runtime.js + your extension bundle)
```

Each layer runs on a **distinct origin** enforced by the browser's same-origin policy. `postMessage` is the only communication channel between layers; there is no shared memory, no shared DOM, and no shared storage.

### Layer 1 — Host (`lumio.vision`)

The host page is the Lumio overlay, widget, or dashboard editor. It owns the real DOM and renders what viewers see. The host communicates exclusively with the Supervisor iframe and never touches extension code directly.

The host creates the Supervisor iframe via `ExtensionWorkerManager` and sends messages to `supervisorIframe.contentWindow.postMessage(...)`.

### Layer 2 — Supervisor (`supervisor.ext.lumio.vision`)

The Supervisor is a minimal (~90-line) vanilla JavaScript page hosted at a separate subdomain. It acts as a **message firewall**:

- Messages arriving from the Extension Runtime (Worker → Host direction) are validated against an allowlist of permitted JSON-RPC methods before being forwarded to the Host.
- Messages arriving from the Host (Host → Worker direction) are validated against a second allowlist before being forwarded to the Extension Runtime.
- Any message with an unknown or disallowed `method` is dropped with a console warning. It is never forwarded in either direction.

JSON-RPC response objects (those with an `id` field but no `method`) are forwarded without method validation, as they are replies to explicit requests.

**Permitted Worker → Host methods:**
`ui.render`, `ui.ready`, `ui.keyframes`, `ui.error`, `storage.set`, `storage.get`, `server.query`, `server.mutation`, `action.execute`

**Permitted Host → Worker methods:**
`lifecycle.init`, `lifecycle.destroy`, `event.callback`, `event.platform`, `storage.update`, `theme.change`

### Layer 3 — Extension Runtime (`ext.lumio.vision`)

The Extension Runtime is another minimal vanilla JavaScript page hosted at a separate subdomain. It:

1. Blocks `localStorage` and `sessionStorage` entirely via `Object.defineProperty` — throwing a `DOMException` on access.
2. Creates the Web Worker (`new Worker(runtimeUrl)`) where your actual extension code runs.
3. Forwards all messages from the Worker to the Supervisor (parent) and vice versa, without additional validation (validation is done at the Supervisor layer).

The storage blocking prevents cross-extension data leakage — all extensions share the `ext.lumio.vision` origin, so browser storage would be shared without this guard. The `useExtensionStorage` SDK hook uses Lumio's Redis-backed storage instead, which is properly scoped per extension.

### Web Worker

Your extension bundle and the Lumio runtime (`lumio-runtime.js`) run inside a Web Worker. This means:

- No DOM access at all — `document` and `window` do not exist in this context.
- React renders through a custom reconciler that serialises the component tree to `LumioComponentNode[]` and sends it to the Host via `ui.render` — the Host renders the actual DOM elements.
- Network requests, storage reads/writes, and server function calls all go through the SDK which routes them via `postMessage` through the Supervisor.

## What extensions can do

| Capability | How |
|------------|-----|
| Render UI components | `Box`, `Text`, `Button`, `Image`, etc. via `@zaflun/lumio-sdk` |
| Read and write extension storage | `useExtensionStorage()` hook |
| Call server functions | `useQuery()`, `useMutation()` hooks |
| Receive platform events | `useLumioEvent()` hook |
| Trigger custom actions | `useLumioAction()` hook |
| Respond to theme changes | `useLumioTheme()` hook |
| Animate UI elements | `defineKeyframes()`, `useAnimation()` |

## What extensions cannot do

| Action | Reason |
|--------|--------|
| Access the DOM directly | Web Worker has no DOM context |
| Use `localStorage` / `sessionStorage` | Blocked by the Extension Runtime |
| Make arbitrary network requests | Only `ctx.fetch()` with declared egress hosts (server functions) |
| Access viewer cookies or JWT tokens | Different origin; cookies are not sent to `ext.lumio.vision` |
| Navigate the top-level page | No access to `window.top` or `window.parent.location` |
| Send undeclared JSON-RPC methods | Supervisor drops unknown methods |
| Access another extension's data | Storage is scoped per extension; no shared globals |

## How this affects development

The sandbox is **transparent** to extension developers. The `lumio dev` CLI sets up local equivalents of all three layers automatically:

- A local Supervisor page at `http://localhost:3200`
- A local Extension Runtime page at `http://localhost:3201`
- Your extension bundle via the Vite dev server at `http://localhost:5173`

You write the same `@zaflun/lumio-sdk` components and hooks as always. The SDK handles all cross-layer communication internally.

## Debugging tips

### Viewing the iframe tree

Open Chrome DevTools → Elements panel. You will see:

```
body
  └─ iframe (src: supervisor.ext.lumio.vision or localhost:3200)
       └─ iframe (src: ext.lumio.vision or localhost:3201)
```

Each iframe has its own DevTools context. Use the context switcher (top-left of the Console panel) to select the Supervisor or Runtime iframe.

### Supervisor console messages

The Supervisor logs a warning when it drops a message:

```
[Supervisor] Blocked worker→host message: some.unknown.method
[Supervisor] Blocked host→worker message: some.unknown.method
```

If you see these messages, a method your extension is trying to use is not in the allowlist. This means either:
- You are calling an internal method that is not part of the SDK's public protocol.
- A version mismatch exists between your extension bundle and the installed runtime.

### Worker errors

Uncaught errors in the Web Worker surface as `ui.error` messages on the Host. You can also inspect them by selecting the Worker context in DevTools → Sources → Threads.

### iframe not loading

If the Supervisor or Extension Runtime iframe fails to load:

- Verify the `NEXT_PUBLIC_SUPERVISOR_URL` and `NEXT_PUBLIC_EXTENSION_RUNTIME_URL` env vars point to reachable origins.
- Check that `CORS` headers allow the host origin. The static apps are served by Cloudflare Pages which sends permissive CORS headers by default.
- In local dev, ensure `just dev-supervisor` (port 3200) and `just dev-runtime` (port 3201) are running.

---

## Guides / AI Assistant

# AI Assistant Integration

Two ways to give your AI coding assistant full Lumio SDK context:

| Approach | Setup | Best for |
|----------|-------|----------|
| **llms.txt** | Zero install — paste a URL | Quick start, one-off questions, any AI tool |
| **Agent Skill** | `npx @zaflun/lumio-agent-skill add` | Persistent per-project context, deep integration |

Both approaches are complementary — use llms.txt for immediate context and the agent skill for ongoing project work.

## llms.txt — Zero-Install Documentation

The Lumio developer docs are available as machine-readable files that any AI assistant can consume directly:

- **[llms.txt](https://developers.lumio.vision/llms.txt)** — structured index of all documentation pages with descriptions
- **[llms-full.txt](https://developers.lumio.vision/llms-full.txt)** — complete documentation (~400 KB) in a single file

### How to use

Paste the URL or file content into your assistant's context window. Most AI tools accept URLs directly:

```
Read https://developers.lumio.vision/llms-full.txt and help me build a loyalty points bot module.
```

Or fetch and pipe the content:

```bash
curl -s https://developers.lumio.vision/llms-full.txt | pbcopy
```

These files are auto-generated from the documentation source on every build — they always reflect the latest published docs.

### When to use llms.txt vs the agent skill

Use **llms.txt** when you want to give an AI assistant context without modifying your project. Useful for:
- Asking questions about the Lumio SDK before starting a project
- One-off code generation in a chat interface
- Tools that support URL fetching but not local skill files

Use the **agent skill** when you want persistent, automatic context on every conversation in your project. The skill files are loaded automatically by supported tools without any manual URL pasting.

## Agent Skill — Per-Project Context

The `@zaflun/lumio-agent-skill` package installs reference files into your extension project that teach AI coding assistants how to build Lumio extensions correctly without you having to explain the SDK every session.

Supported tools: **Claude Code**, **GitHub Copilot**, **Cursor**, **Google Gemini CLI**, **OpenAI Codex**, **Windsurf**, and any agent that reads `SKILL.md`, `AGENTS.md`, or `GEMINI.md`.

## What it installs

Running the setup command creates a `.lumio/skills/` directory in your project with the following files:

| File | Purpose |
|------|---------|
| `SKILL.md` | Entry point — overview of the Lumio Extension SDK, conventions, and link map to other files |
| `components.md` | All SDK UI components (`<Layout>`, inputs, display elements) with prop signatures |
| `server-functions.md` | Declarative and handler-based server function patterns, storage scoping, external API calls |
| `cli-workflows.md` | `lumio dev`, `lumio build`, `lumio deploy`, `lumio logs` — full CLI reference |
| `auth.md` | Auth context, identity hooks, OAuth scope requirements |
| `runtime-scopes.md` | Surface targeting (`layer`, `editor`, `interactive`), sandbox constraints |
| `best-practices.md` | Performance, state management, extension manifest dos and don'ts |
| `troubleshooting.md` | Common errors and how to fix them |

AI assistants that read these files understand:

- How `config_schema` fields map to rendered UI inputs in the extension editor panel
- Which hooks (`useLumioConfig`, `useLumioEvent`, `useExtensionStorage`) are available in which surfaces
- How to call external APIs from server functions without hitting the sandbox boundary
- The correct way to declare permissions and egress rules in `lumio.config.ts`

## Installation

Install the CLI globally and run the setup command inside your extension project:

```bash
npm install -g @zaflun/lumio-agent-skill
npx lumio-skills add
```

This creates `.lumio/skills/` with all reference files. The directory is safe to commit to your repository — it contains only read-only reference markdown, no secrets or generated code.

### Single-run alternative

If you prefer not to install globally, use `npx` directly:

```bash
npx @zaflun/lumio-agent-skill add
```

## Using with Claude Code

Claude Code reads `.lumio/skills/SKILL.md` automatically when it is present in the working tree. No additional configuration is required — open your extension project directory in Claude Code and the assistant is already primed with Lumio context.

To manually point the assistant to a skill file, reference it in your prompt:

```
Read .lumio/skills/server-functions.md and help me add an external API call to my scoreboard handler.
```

## Using with GitHub Copilot

Copilot picks up the skill files as workspace context when they are open in an editor tab or referenced in a prompt. For consistent context across a session, add the skill directory to your Copilot workspace instructions (`.github/copilot-instructions.md`):

```markdown
See .lumio/skills/SKILL.md for Lumio Extension SDK conventions.
```

## Using with Cursor

Cursor's `@Docs` and `@File` context commands work with the skill files directly:

```
@File .lumio/skills/components.md What inputs are available for a config_schema field of type "select"?
```

You can also add `.lumio/skills/` to your Cursor project rules so Cursor loads the SKILL.md on every new conversation.

## Using with Google Gemini CLI

Gemini CLI reads `GEMINI.md` in the project root. Create one that references the skill files:

```markdown
<!-- GEMINI.md -->
## Lumio Extension SDK

This project is a Lumio extension. Read `.lumio/skills/SKILL.md` for the full SDK reference including components, hooks, server functions, and CLI commands.

For detailed references see:
- `.lumio/skills/components.md` — UI components
- `.lumio/skills/server-functions.md` — Server function patterns
- `.lumio/skills/cli-workflows.md` — CLI commands
```

Gemini loads this file automatically at session start.

## Using with OpenAI Codex / ChatGPT

Codex reads `AGENTS.md` in the project root. Create one:

```markdown
<!-- AGENTS.md -->
## Lumio Extension SDK

This project is a Lumio extension built with `@zaflun/lumio-sdk`.
Read `.lumio/skills/SKILL.md` for the complete SDK reference.
```

This also works with any agent that follows the `AGENTS.md` convention.

## Using with Windsurf

Windsurf reads `.windsurfrules` in the project root. Create one:

```
Read .lumio/skills/SKILL.md for Lumio Extension SDK conventions.
This project uses @zaflun/lumio-sdk for components and hooks, and @zaflun/lumio-cli for development.
```

Windsurf will load this on every new conversation in the project.

## Keeping skills up to date

The skill files are versioned with `@zaflun/lumio-agent-skill`. When the Lumio SDK is updated, re-run the same command to overwrite the old files with the latest reference:

```bash
npx lumio-skills add
```

The command is idempotent — running it multiple times is safe and always writes the version that matches your currently installed `@zaflun/lumio-agent-skill` package.

To update to the latest published version and refresh the skill files in one step:

```bash
npm install -g @zaflun/lumio-agent-skill@latest && npx lumio-skills add
```

## What the assistant will not do

The skill files are reference documentation, not executable code. They teach the assistant Lumio patterns but do not grant it access to your Lumio account, API keys, or extension runtime. The assistant generates code; you review, test with `lumio dev`, and deploy with `lumio deploy`.

---

## Guides / Bot Modules

# Bot Modules

> **Built-in modules:**
> Lumio's built-in bot modules (Link Protection, Spam Protection, Word Filter, Timed Messages) are **system extensions** that run through the same V8 execution model as third-party bot modules. All bot modules -- built-in and custom -- use the same SDK handlers (`defineCommand`, `defineModerate`, etc.).
Bot modules are extensions that handle chat messages, platform events, and timed actions across Twitch, YouTube, Kick, Trovo, and Discord. They run server-side in a V8 isolate — no browser required.

This guide walks through creating a bot module from scratch, writing handlers, testing locally, and deploying.

## Prerequisites

- Node.js 22.13+
- A Lumio developer account
- The `@zaflun/lumio-cli` package installed globally

```bash
npm install -g @zaflun/lumio-cli
lumio login
```

## Create a bot module project

Use `lumio init` and select the `bot_module` category:

```bash
lumio init my-bot-module
```

When prompted:

- **Category:** `bot_module`
- **Platforms:** Select one or more: `twitch`, `youtube`, `kick`, `trovo`, `discord`
- **Server functions:** Yes (auto-enabled for bot modules)

This generates the following project structure:

```
my-bot-module/
├── lumio.config.json
├── server/
│   ├── schema.ts
│   └── functions.ts
├── package.json
└── tsconfig.json
```

Bot modules have no `src/` directory — they are server-only extensions with no browser UI surface.

## Configure the manifest

Open `lumio.config.json` and define your triggers and permissions:

```json
{
  "$schema": "https://lumio.vision/schemas/lumio.config.schema.json",
  "extension_id": "your-uuid-here",
  "name": "My Bot Module",
  "category": "bot_module",
  "version": "1.0.0",
  "platforms": ["twitch", "youtube"],
  "server": true,
  "permissions": ["chat:send", "chat:read"],
  "triggers": {
    "commands": [
      {
        "name": "hello",
        "description": "Greet the user",
        "cooldown_global": 5,
        "cooldown_user": 10,
        "min_role": "everyone"
      }
    ],
    "keywords": ["gg"],
    "events": ["twitch:subscribe"],
    "timers": [
      {
        "name": "reminder",
        "interval": 300,
        "handler": "periodicReminder"
      }
    ]
  },
  "config_schema": [
    {
      "key": "greeting",
      "type": "string",
      "label": "Greeting message",
      "default_value": "Hello",
      "required": true
    }
  ]
}
```

Key differences from widget/overlay extensions:

- **`category`** must be `"bot_module"`
- **`platforms`** declares which chat platforms this module supports
- **`triggers`** defines when handlers fire (commands, keywords, patterns, events, timers)
- **`targets`** is not used — bot modules have no visual surfaces

## Define the database schema

If your module needs persistent storage, define tables in `server/schema.ts`:

```typescript
// server/schema.ts
import { defineSchema, defineTable, column } from "@zaflun/lumio-sdk/server";

export default defineSchema({
  greetings: defineTable({
    user_id: column.string(),
    count: column.number(),
    last_greeted: column.number(),
  }),
});
```

## Write handlers

Bot modules use handler wrappers from `@zaflun/lumio-sdk/server`. Each wrapper corresponds to a trigger type:

```typescript
// server/functions.ts
import { command, keyword, event, timer } from "@zaflun/lumio-sdk/server";

// Command handler — fires when a user types !hello
export const hello = command("hello", async (ctx, args) => {
  const greeting = ctx.config.greeting ?? "Hello";
  return { reply: `${greeting}, ${ctx.user.name}!` };
});

// Keyword handler — fires when "gg" appears in chat
export const hypeDetector = keyword("gg", async (ctx, message) => {
  await ctx.cache.increment("hype_count", 1);
  return null; // no reply
});

// Event handler — fires on Twitch subscriptions
export const welcomeSub = event("twitch:subscribe", async (ctx, evt) => {
  return {
    reply: `Welcome ${evt.user_name}! Thanks for subscribing!`,
  };
});

// Timer handler — fires every 300 seconds
export const periodicReminder = timer("reminder", async (ctx) => {
  return { reply: "Remember to follow the channel!" };
});
```

Every handler receives a `ctx` object with access to the database, cache, secrets, config, and more. See the [Bot Module Context](/sdk/hooks/bot-module-context) reference for the full API.

## Handler types

| Wrapper | Trigger | Execution | Return |
|---------|---------|-----------|--------|
| `command(name, handler)` | Chat prefix (`!name`) | Sync (500ms deadline) | `{ reply?: string }` |
| `keyword(word, handler)` | Substring match | Async (fire-and-forget) | `{ reply?: string }` or `null` |
| `pattern(regex, handler)` | Regex match | Async (fire-and-forget) | `{ reply?: string }` or `null` |
| `event(type, handler)` | Platform event | Async (fire-and-forget) | `{ reply?: string }` or `null` |
| `timer(name, handler)` | Interval clock | Async (self-triggered) | `{ reply?: string }` or `null` |
| `moderate(handler)` | Every message | Sync (500ms deadline) | `{ block: boolean }` |

## Test locally

Start the bot module dev server:

```bash
lumio dev --bot-module
```

This launches a chat simulator where you can type messages and see handler responses in real time. See [Local Development](/guides/bot-module-local-dev) for details.

You can also test individual handlers:

```bash
lumio run command:hello --args "" --user "testuser"
```

## Deploy

Build and deploy like any other extension:

```bash
lumio deploy
```

After deployment, the bot module appears in the Lumio Store under the **Bot Module** category. Users install it from the Store and configure triggers, cooldowns, and settings in their dashboard.

## What happens at runtime

1. A chat message arrives at the platform bot (Twitch, YouTube, etc.)
2. The bot runs built-in modules first (link protection, word filter, spam protection)
3. The bot matches the message against installed extension triggers (commands, keywords, patterns)
4. On match, the bot dispatches to the Bot Module Worker via HTTP (sync) or Redis (async)
5. The Worker executes your handler in a V8 isolate
6. The handler response (reply, moderation action) is sent back to the bot
7. The bot delivers the response to chat

## Next steps

- [Local Development](/guides/bot-module-local-dev) — chat simulator, hot-reload, mock users
- [Bot Module Context](/sdk/hooks/bot-module-context) — full `ctx` API reference
- [Triggers](/config/triggers) — trigger configuration reference
- [Security](/guides/bot-module-security) — rate limits, permissions, audit log
- [Cache & Background Jobs](/guides/cache-and-defer) — `ctx.cache` and `ctx.defer()` usage
- [Examples](/examples/loyalty-points) — complete bot module examples

---

## Guides / Bot Module Local Development

# Bot Module Local Development

Bot modules have no browser UI, so `lumio dev` provides a CLI-based chat simulator for interactive testing. This guide covers the dev server, single-handler testing, hot-reload, and mock users.

## Start the dev server

```bash
lumio dev --bot-module
```

Output:

```
Bot Module Dev Server running
Extension: My Bot Module (install: dev-local)
Platform: twitch (simulated)
Type chat messages below. Prefix with @username to set sender.

>
```

The dev server:

- Loads your `lumio.config.json` and `server/functions.ts`
- Connects to your local Extensions-DB for `ctx.db` operations
- Connects to local Redis for `ctx.cache` operations
- Watches `server/functions.ts` for changes and hot-reloads automatically
- Fires timers at their configured intervals

## Interactive chat

Type messages at the prompt to simulate chat input:

```
> !hello
[hello] Reply: "Hello, dev_user!"

> gg
[hypeDetector] (silent - no reply)
[hypeDetector] Deferred: ctx.cache.increment("hype_count", 1)

> https://clips.twitch.tv/FunnyClip123
[clipLogger] Reply: "Clip from dev_user: https://clips.twitch.tv/FunnyClip123"
```

The simulator shows handler responses, actions, and deferred jobs in real time.

## Mock users

Prefix your message with `@username` to simulate different senders:

```
> @viewer_jane !hello
[hello] Reply: "Hello, viewer_jane!"
```

Set roles with a role prefix before the username:

| Prefix | Role |
|--------|------|
| `@username` | `everyone` (default) |
| `@sub:username` | `subscriber` |
| `@vip:username` | `vip` |
| `@mod:username` | `moderator` |
| `@broadcaster:username` | `broadcaster` |

Examples:

```
> @sub:loyal_viewer !gamble 50
[gamble] Reply: "loyal_viewer won 100 points!"

> @mod:nightbot !clear
[clear] Reply: "Chat cleared by nightbot"
```

The simulated user object populates `ctx.user` with the appropriate `id`, `name`, `role`, `isMod`, `isVip`, and `isSub` fields.

## Single handler testing

Test a specific handler directly without the interactive chat:

```bash
# Test a command handler with arguments
lumio run command:hello --args "" --user "testuser" --role "subscriber"

# Test a keyword handler
lumio run keyword:hypeDetector --message "gg wp nice one" --user "viewer123"

# Test a pattern handler
lumio run pattern:clipLogger --message "check this https://clips.twitch.tv/abc123" --user "clipper"

# Test an event handler
lumio run event:welcomeSub --event '{"user_name": "newSub", "cumulative_months": 3}'

# Test a moderation handler
lumio run moderate:linkFilter --message "go to banned-site.com for free stuff" --user "spammer"
```

Each `lumio run` invocation:

1. Loads the extension config and handler code
2. Creates a mock context with the specified user and role
3. Executes the handler once
4. Prints the response and any side effects (DB writes, cache ops, deferred jobs)
5. Exits

## Hot-reload

The dev server watches `server/functions.ts` and related files. When you save a change, handlers are reloaded automatically:

```
[hot-reload] Detected change in server/functions.ts
[hot-reload] Handlers reloaded (3 commands, 2 keywords, 1 timer)
```

The reload preserves your chat history and in-memory state. Timers are restarted with potentially new intervals.

## Timer testing

Timers fire at their configured intervals during `lumio dev`. For faster iteration, you can trigger a timer manually:

```
> /timer reminder
[periodicReminder] Reply: "Remember to follow the channel!"
```

The `/timer <name>` command fires the named timer handler immediately without waiting for the interval.

## Platform simulation

By default, the dev server simulates Twitch. Switch platforms with:

```
> /platform youtube
Platform switched to: youtube

> /platform kick
Platform switched to: kick
```

This changes the `ctx.user.platform` value for subsequent messages.

## Database and cache

The dev server uses your local infrastructure:

- **Database:** Local Extensions-DB (port 5434). Tables from `server/schema.ts` are provisioned automatically.
- **Cache:** Local Redis. Cache keys are scoped under `ext-cache:dev-local:*`.

Both persist across dev server restarts, so you can build up test data over time.

## Debugging

The dev server prints detailed output for each handler invocation:

```
> !points
[points] Executing command handler...
[points] ctx.cache.get("pts:viewer123") → 150
[points] ctx.cache.set("pts:viewer123", 151, 3600) → OK
[points] Reply: "viewer123: 151 points"
[points] Deferred: 1 job queued
[points] Deferred[0]: ctx.db.patch("user_points", "viewer123", {"balance": 151}) → OK
[points] Completed in 8ms
```

This shows every `ctx.db`, `ctx.cache`, and `ctx.fetch` call made by the handler, along with deferred job execution.

## Production debugging

After deploying your bot module, use `lumio logs` to stream production handler execution logs:

```bash
# Stream all logs
lumio logs

# Filter by handler
lumio logs --handler points

# Filter by level
lumio logs --level error
```

See [Error Reporting](/guides/error-reporting) for information about the anonymized error reports available in the developer dashboard.

---

## Guides / Bot Module Security

# Bot Module Security

Bot modules execute third-party code that can send chat messages and perform moderation actions. Lumio enforces multiple security layers to protect streamers, viewers, and the platform.

## V8 isolation

Every handler invocation runs inside an isolated V8 sandbox with strict resource limits:

| Limit | Sync path (commands, moderation) | Async path (keywords, patterns, events, timers) |
|-------|----------------------------------|--------------------------------------------------|
| CPU timeout | 500ms | 10s |
| Memory | 256 MB heap | 256 MB heap |
| Response size | 4 MB | 4 MB |

Each extension install gets its own V8 isolate. Isolates share no state — one extension cannot access another extension's memory, variables, or closures.

## Database isolation

Each extension install gets its own PostgreSQL schema (`ext_{install_id}`). Extensions cannot query core Lumio tables (users, accounts, overlays) or other extensions' schemas.

## Cache isolation

`ctx.cache` operations are scoped to `ext-cache:{install_id}:*` in Redis. The Rust worker prepends this prefix before executing any Redis command. Extensions cannot access other extensions' cache keys or any internal Lumio Redis keys.

## Egress restrictions

`ctx.fetch()` only allows HTTPS requests to hostnames declared in the `egress.allowHosts` manifest field. Private IP ranges (`10.*`, `172.16-31.*`, `192.168.*`, `127.*`, link-local) are blocked at two layers:

1. **URL hostname check** — literal IP addresses in the URL are rejected
2. **Post-DNS-resolution check** — after DNS resolution, every resolved IP is validated against private ranges, preventing DNS rebinding attacks

## Redis isolation

Extension JavaScript has no direct Redis access. There is no `ctx.redis` API. All Redis operations (`ctx.cache`, cooldowns, rate limits, pub/sub) are performed by trusted Rust code in the Worker. Redis keys are constructed from validated install IDs — extension input is never interpolated into key names.

## Permission tiers

Extensions declare required permissions in `lumio.config.json`. Each permission goes through store review:

| Permission | Review level | Notes |
|------------|-------------|-------|
| `chat:read` | Standard | Reading chat messages |
| `chat:send` | Standard | Sending chat replies |
| `events:read` | Standard | Receiving platform events |
| `chat:delete` | Enhanced manual review | Deleting chat messages |
| `chat:ban` | Enhanced manual review | Banning or timing out users |

Extensions requesting `chat:ban` or `chat:delete` undergo additional manual code review during the store approval process. Reviewers verify that moderation logic is sound and that the extension cannot be exploited to mass-ban or mass-delete.

## Rate limits

All actions are rate-limited per installation to prevent abuse:

### Handler invocation limits

| Category | Limit | Scope |
|----------|-------|-------|
| Command execution | 60/min | Per install |
| Keyword/pattern execution | 100/min | Per install |
| Event handler execution | 50/min | Per install |
| Timer execution | 1/interval | Per install |

### Action output limits

| Action | Limit | Scope |
|--------|-------|-------|
| Chat send | 30/min | Per install |
| Ban | 5/min | Per install |
| Timeout | 10/min | Per install |
| Delete message | 20/min | Per install |
| Cache operations | 200/min | Per install |

Rate limits are enforced at two layers:

1. **Input:** Limits how often a handler is invoked
2. **Output:** Limits what actions the handler can produce, regardless of which handler type generated them

A keyword handler that returns a ban action is still subject to the 5/min ban limit. This prevents bypassing moderation rate limits by splitting actions across handler types.

## Trigger limits

Each extension is limited in how many triggers it can declare:

| Trigger type | Maximum per extension |
|-------------|----------------------|
| Commands | 20 |
| Keywords | 50 |
| Patterns (regex) | 10 |
| Keyword minimum length | 3 characters |
| Pattern maximum length | 200 characters |

Regex patterns are validated for safety. The Rust `regex` crate guarantees linear-time matching (no backreferences or lookaheads), making ReDoS attacks impossible by construction. Pattern matching runs in Rust on the bot side — JavaScript `RegExp` is never used for trigger matching.

## Moderation fail-closed policy

When the sync moderation path times out (500ms), the bot applies a configurable default policy:

| Policy | Behavior |
|--------|----------|
| `allow` (default) | Message passes through |
| `hold` | Message is held and auto-deleted after 5 seconds if no response |

The policy is configured per account in bot module settings, not per extension. Most streamers use `allow` to avoid false positives from slow responses.

## Audit log

Every moderation action executed by a bot module extension is logged to the platform audit log with:

- **Source:** `extension:{install_id}`
- **Metadata:** Extension name, extension ID, handler name
- **Action:** The specific moderation action (ban, timeout, delete)
- **Reason:** Prefixed with the extension name for traceability

Account owners can view extension-originated moderation actions separately from manual and built-in module actions in the dashboard audit log.

## Kill switch

Every account has a "Pause all extension modules" toggle in the dashboard. When activated:

1. A signal is published to all connected bots and the Worker
2. All extension bot module processing stops immediately for that account
3. All pending deferred jobs for that account are cancelled immediately
4. Built-in modules (link protection, word filter, spam protection) continue operating normally

The kill switch is designed for emergencies — if a malicious extension starts banning legitimate users, the streamer can stop all extension modules with one click.

## Built-in module priority

Built-in modules (LinkProtection, WordFilter, SpamProtection) always run before extension modules. If a built-in module blocks a message, extension `moderate()` handlers are not invoked. Built-in modules execute in under 1ms with no V8 overhead.

## Error isolation

Handler errors are contained within the isolate:

| Scenario | Behavior |
|----------|----------|
| Handler throws an exception | Error logged, no message sent to chat |
| Handler times out (sync) | Command silently dropped, moderation applies default policy |
| Handler times out (async) | Handler killed, error logged |
| Handler returns invalid data | Treated as null response, warning logged |
| `ctx.db` error | Promise rejects inside handler |
| `ctx.fetch` blocked | Promise rejects with `EgressDenied` error |
| Rate limit exceeded | Handler not invoked, message silently dropped |

---

## Guides / Bot Module Updates

# Bot Module Updates

When you publish a new version of your bot module, Lumio updates all installations while preserving every customization the user has made. This page explains the update lifecycle and the override resolution system.

## Override resolution

Every configurable field follows a single rule:

```
resolved_value = COALESCE(user_override, extension_default)
```

If the user has set a custom value, that value is used. If not, the extension default is used. User overrides are never overwritten by extension updates.

## What users can override

Users customize bot modules through the dashboard settings panel:

| Setting | Extension provides | User can override |
|---------|-------------------|-------------------|
| Command cooldown (global) | Default value | Custom value |
| Command cooldown (per-user) | Default value | Custom value |
| Command min role | Default value | Raise (not lower) the minimum role |
| Command enabled | `true` | Toggle on/off |
| Command alias | Name from manifest | Alternative name (e.g. `punkte` for `points`) |
| Keyword enabled | `true` | Toggle on/off per keyword |
| Custom keywords | None | User-added keywords |
| Timer interval | Default interval | Custom interval |
| Timer enabled | `true` | Toggle on/off |
| Config values | Defaults from `config_schema` | Custom values |

## Update flow

When you publish a new version:

```
Developer publishes new version
  |
  v
API marks version as "published"
  |
  v
Auto-update enabled?
  -> Yes: automatic install
  -> No: Update badge in dashboard, user clicks "Update"
  |
  v
extension_installs.version_id updated
  |
  v
Three things happen:
  1. Config migration
  2. Trigger sync
  3. Worker + bot reload
```

### 1. Config migration (non-destructive)

| Change | Result |
|--------|--------|
| New `config_schema` field added | Default value inserted (user has no override yet) |
| `config_schema` field removed | User override kept as dead data, cleaned on next save |
| Default value changed | No effect on users with existing overrides |
| Default value changed | Users without overrides get the new default |

### 2. Trigger sync (non-destructive)

| Change | Result |
|--------|--------|
| New command added | Appears with extension defaults, no user override |
| Command removed | User overrides for that command are cleaned up |
| Command renamed | Old name removed (with override cleanup), new name appears with defaults |
| Cooldown/role defaults changed | No effect on users with overrides |
| New keyword added | Appears enabled by default |
| Keyword removed | User overrides cleaned up |
| New pattern added | Appears enabled by default |
| Pattern removed | Cleaned up |
| New timer added | Appears enabled with default interval |
| Timer removed | User overrides cleaned up |
| Timer interval changed | No effect on users with custom intervals |
| Handler logic changed | New code loaded, no config impact |

User-added custom keywords are always preserved across updates.

### 3. Worker and bot reload

After the update:

- Bots reload the extension trigger lists (commands, keywords, patterns, moderation flag)
- The Worker invalidates its V8 cache, loads the new handler code, and restarts timers with current intervals

## Update safety matrix

| What changed | User has override? | Result |
|--------------|-------------------|--------|
| Default cooldown 5s to 3s | Yes (10s) | User keeps 10s |
| Default cooldown 5s to 3s | No | User gets new default 3s |
| New command added | N/A | Appears with extension defaults |
| Command removed | Yes | Override cleaned up, command gone |
| New config field | N/A | Default value inserted |
| Config field removed | Yes | Override kept (dead data, cleaned on save) |
| Keyword added | N/A | Enabled by default |
| Keyword removed | Yes (disabled) | Override cleaned up |
| User-added keyword | N/A | Preserved, never touched by updates |
| Handler logic changed | N/A | New code loaded, no config impact |
| Timer interval changed | Yes (custom) | User keeps custom interval |
| Timer interval changed | No | User gets new default |
| New timer added | N/A | Appears enabled with default interval |

## Best practices for updates

### Adding new features

When adding new commands, keywords, or config fields, users get sensible defaults automatically. No migration code is needed.

```json
{
  "triggers": {
    "commands": [
      { "name": "points", "description": "Existing command" },
      { "name": "leaderboard", "description": "New command in v1.1.0" }
    ]
  },
  "config_schema": [
    { "key": "pointsPerMessage", "type": "number", "label": "Points per message", "default_value": 1 },
    { "key": "leaderboardSize", "type": "number", "label": "Leaderboard entries", "default_value": 10 }
  ]
}
```

### Removing features

When removing a command or config field, the user's overrides are cleaned up automatically. No manual cleanup code is needed.

### Renaming commands

If you rename a command (e.g., `!pts` to `!points`), the old command is removed and the new one appears with defaults. Users who had aliases on the old command will need to reconfigure them. Consider this when renaming commands in minor versions.

### Changing defaults

Changing a default cooldown or config value only affects users who have not customized that setting. Users with overrides keep their customized values. This means you can safely adjust defaults without disrupting existing users.

---

## Guides / Discord Slash Commands

# Discord Slash Commands

When a bot module declares `"discord"` in its `platforms` array, its commands are automatically registered as Discord slash commands. This page explains the mapping, `discord_options`, and the registration lifecycle.

## How it works

Extension developers declare commands once in `lumio.config.json`. Lumio handles the platform-specific dispatch:

| Platform | User types | Matching method |
|----------|-----------|-----------------|
| Twitch | `!points 100` | IRC prefix match |
| YouTube | `!points 100` | Chat prefix match |
| Kick | `!points 100` | Chat prefix match |
| Trovo | `!points 100` | Chat prefix match |
| Discord | `/points amount:100` | Slash command interaction |

Your handler code is identical for all platforms. The `args` array is populated the same way regardless of where the command originated:

- Prefix command `!points 100` produces `args: ["100"]`
- Discord slash command `/points amount:100` produces `args: ["100"]` (positional from option order)

## Registration flow

When an extension with Discord support is installed on an account that has a Discord connection:

1. The API reads the extension manifest commands
2. The API registers Discord slash commands via the Discord API (`POST /applications/{app_id}/guilds/{guild_id}/commands`)
3. The Discord bot receives interactions via the Discord Gateway
4. The bot dispatches to the Worker using the same sync HTTP path as prefix commands

Discord may take up to 1 hour to propagate guild-level command changes.

## Adding `discord_options`

By default, commands are registered as simple slash commands with no options. To add typed parameters, use the `discord_options` field:

```json
{
  "triggers": {
    "commands": [
      {
        "name": "points",
        "description": "Show a user's points balance",
        "cooldown_global": 5,
        "min_role": "everyone",
        "discord_options": [
          {
            "name": "user",
            "type": "user",
            "description": "User to check",
            "required": false
          }
        ]
      },
      {
        "name": "give",
        "description": "Give points to another user",
        "cooldown_global": 10,
        "min_role": "moderator",
        "discord_options": [
          {
            "name": "user",
            "type": "user",
            "description": "Recipient",
            "required": true
          },
          {
            "name": "amount",
            "type": "integer",
            "description": "Points to give",
            "required": true
          }
        ]
      }
    ]
  }
}
```

### Option types

| Type | Discord type | Description |
|------|-------------|-------------|
| `"string"` | `STRING` | Text input |
| `"integer"` | `INTEGER` | Whole number |
| `"boolean"` | `BOOLEAN` | True/false toggle |
| `"user"` | `USER` | Discord user mention picker |
| `"channel"` | `CHANNEL` | Channel picker |
| `"role"` | `ROLE` | Role picker |

Non-Discord platforms ignore the `discord_options` field entirely.

### Args mapping

Discord options are mapped to the `args` array by position (order of declaration):

```json
{
  "discord_options": [
    { "name": "user", "type": "user", "required": true },
    { "name": "amount", "type": "integer", "required": true }
  ]
}
```

When a user runs `/give user:@jane amount:50`, the handler receives `args: ["jane_user_id", "50"]` — matching the declaration order.

For prefix platforms, `!give @jane 50` produces the same `args: ["@jane", "50"]`.

## Handling Discord-specific behavior

Your handler can check `ctx.user.platform` to detect which platform triggered the command:

```typescript
import { command } from "@zaflun/lumio-sdk/server";

export const points = command("points", async (ctx, args) => {
  const targetUser = args[0] ?? ctx.user.id;
  const points = await ctx.db.get("user_points", targetUser);

  if (ctx.user.platform === "discord") {
    // Discord supports richer formatting
    return { reply: `**${ctx.user.displayName}** has **${points?.balance ?? 0}** points` };
  }

  return { reply: `${ctx.user.displayName} has ${points?.balance ?? 0} points` };
});
```

## Sync on update

When you publish a new version that changes commands:

1. Old Discord slash commands are removed
2. New commands are registered with the Discord API
3. Discord propagates changes (up to 1 hour for guild commands)

During the propagation window, users may see stale commands in the Discord autocomplete. This is a Discord API limitation.

## Discord-only triggers

Keywords and patterns work in Discord the same as other platforms — they match against message content in text channels. Events use Discord-specific event types if available.

Timers fire to Discord channels the same way they fire to other platforms.

---

## Guides / Cache & Background Jobs

# Cache & Background Jobs

Bot modules (and all extension types) have access to two complementary APIs for performance optimization: `ctx.cache` for fast Redis-backed temporary storage, and `ctx.defer()` for queuing background work after the handler returns.

Each API works independently. You can use cache without defer, defer without cache, or combine them for patterns like cache-first reads with background DB persistence.

## `ctx.cache` — Scoped Redis cache

A key-value cache backed by Redis, scoped to the extension installation. Provides sub-millisecond reads and writes without the overhead of a database round-trip.

### API

```typescript
ctx.cache = {
  get: (key: string) => Promise<unknown | null>,
  set: (key: string, value: unknown, ttl?: number) => Promise<void>,
  delete: (key: string) => Promise<void>,
  increment: (key: string, by?: number) => Promise<number>,
};
```

### Basic usage

```typescript
import { command } from "@zaflun/lumio-sdk/server";

export const counter = command("count", async (ctx) => {
  // Increment a counter (creates the key with value 0 if it does not exist)
  const count = await ctx.cache.increment("message_count", 1);
  return { reply: `Message count: ${count}` };
});
```

### Setting values with TTL

```typescript
// Store a value with a 5-minute TTL
await ctx.cache.set("last_clipper", ctx.user.name, 300);

// Store a value with the default TTL (1 hour)
await ctx.cache.set("status", "active");

// Read it back
const status = await ctx.cache.get("status"); // "active" or null if expired
```

### Deleting values

```typescript
await ctx.cache.delete("spam_score:user123");
```

### Key scoping

Your extension only provides the key name. The Rust Worker automatically prepends `ext-cache:{install_id}:` before executing any Redis command:

```
Extension calls:  ctx.cache.set("score:user123", 42, 3600)
Redis executes:   SET ext-cache:{install_id}:score:user123 42 EX 3600
```

You cannot access other extensions' cache keys or any internal Lumio Redis keys.

### Key format rules

Keys must match the pattern `^[a-zA-Z0-9:_-]+$` — alphanumeric characters plus `:`, `_`, and `-`. This validation is enforced in Rust (not JavaScript), so it cannot be bypassed.

### Limits

| Limit | Value |
|-------|-------|
| Max TTL | 24 hours (86,400 seconds) |
| Default TTL | 1 hour (3,600 seconds) |
| Max key length | 128 characters |
| Max value size | 64 KB |
| Max keys per install | 1,000 |
| Operations rate limit | 200 ops/min per install |
| No-TTL behavior | Keys without explicit TTL get the 1-hour default |

There are no wildcard operations (`KEYS`, `SCAN`). Extensions cannot enumerate their own keys.

### When to use cache vs database

| Use case | Use `ctx.cache` | Use `ctx.db` |
|----------|----------------|-------------|
| Cooldown counters | Yes | No |
| Spam scores | Yes | No |
| "Last chatter" queue | Yes | No |
| Temporary vote counts | Yes | No |
| User point balances (fast reads) | Yes (with DB backup) | Yes (source of truth) |
| Leaderboards | No | Yes |
| Permanent user data | No | Yes |
| Historical logs | No | Yes |

---

## `ctx.defer()` — Background jobs

Queues a function that the Worker executes **after** the handler returns. The handler can respond to the user immediately while expensive work runs in the background — outside the 500ms sync deadline.

### API

```typescript
ctx.defer(fn: () => Promise<void>): void
```

### Basic usage

```typescript
import { command } from "@zaflun/lumio-sdk/server";

export const points = command("points", async (ctx, args) => {
  const balance = 100; // fast calculation

  // Reply immediately
  // Background work runs after this return
  ctx.defer(async () => {
    // This runs after the reply is sent
    await ctx.db.insert("point_history", {
      user_id: ctx.user.id,
      action: "check",
      timestamp: Date.now(),
    });
  });

  return { reply: `${ctx.user.name}: ${balance} points` };
});
```

### Limits

| Limit | Value |
|-------|-------|
| Max deferred calls per handler | 5 |
| Timeout per deferred call | 10 seconds |
| Available APIs | `ctx.db`, `ctx.cache`, `ctx.fetch`, `ctx.secrets` |
| Error handling | Logged to Sentry, not surfaced to the chat user |

### Multiple deferred calls

You can queue up to 5 deferred calls per handler invocation. They execute sequentially after the handler returns:

```typescript
export const gamble = command("gamble", async (ctx, args) => {
  const result = Math.random() > 0.5 ? "win" : "lose";

  ctx.defer(async () => {
    await ctx.db.patch("user_points", ctx.user.id, {
      balance: result === "win" ? 200 : 50,
    });
  });

  ctx.defer(async () => {
    await ctx.db.insert("gamble_history", {
      user_id: ctx.user.id,
      result,
      timestamp: Date.now(),
    });
  });

  return { reply: `${ctx.user.name} ${result === "win" ? "won" : "lost"}!` };
});
```

### Error handling

If a deferred call throws an exception or times out, the error is logged but does not affect the user. The chat reply has already been sent. Errors from deferred calls appear in the developer dashboard error reports and `lumio logs`.

---

## Combined pattern: cache-first with background persist

The most common pattern combines `ctx.cache` for fast reads with `ctx.defer()` for background database writes:

```typescript
import { command } from "@zaflun/lumio-sdk/server";

export const points = command("points", async (ctx, args) => {
  // Fast: read from cache (~1ms)
  const cached = (await ctx.cache.get(`pts:${ctx.user.id}`)) as number | null;
  const balance = cached ?? 0;
  const newBalance = balance + 1;

  // Fast: write to cache (~1ms)
  await ctx.cache.set(`pts:${ctx.user.id}`, newBalance, 3600);

  // Slow: persist to DB in background (~5-20ms, runs after reply)
  ctx.defer(async () => {
    await ctx.db.patch("user_points", ctx.user.id, { balance: newBalance });
    await ctx.db.insert("point_history", {
      user_id: ctx.user.id,
      amount: 1,
      timestamp: Date.now(),
    });
  });

  return { reply: `${ctx.user.name}: ${newBalance} points` };
});
```

This pattern keeps the handler response under the 500ms sync deadline while ensuring data eventually reaches the database.

### Comparison

| | `ctx.cache` | `ctx.db` | `ctx.defer()` |
|---|------------|---------|--------------|
| Backend | Redis | PostgreSQL | V8 (background) |
| Persistence | Temporary (TTL) | Permanent | N/A (orchestrator) |
| Latency | ~1ms | ~5-20ms | Async (after return) |
| Use case | Counters, cooldowns | User data, leaderboards | Background jobs |

---

## Guides / Error Reporting

# Error Reporting

When your bot module (or any extension) throws errors in production, Lumio collects anonymized error reports and makes them available in the developer dashboard. You get full visibility into what went wrong without accessing any personally identifiable information from the accounts that have your extension installed.

## What you can see

The developer error dashboard shows:

| Data | Visible | Example |
|------|---------|---------|
| Error message | Yes (sanitized) | `TypeError: Cannot read property 'balance' of null` |
| Stack trace | Yes | `at points (server/functions.ts:5:42)` |
| Handler name | Yes | `points` |
| Trigger type | Yes | `command` |
| Platform | Yes | `twitch` |
| Extension version | Yes | `1.2.0` |
| Sanitized arguments | Yes | `["100"]` |
| Config key names | Yes | `[pointsPerMessage, gamblingEnabled]` |
| User role | Yes | `subscriber` |
| Execution time | Yes | `12ms` |
| Occurrence count | Yes | `34` |
| Affected install count | Yes | `3 of 150` |
| Anonymous account hash | Yes | `anon_a1b2c3` |
| Anonymous install hash | Yes | `anon_d4e5f6` |

## What you cannot see

| Data | Why |
|------|-----|
| Account ID | HMAC-hashed, not reversible |
| Install ID | HMAC-hashed, not reversible |
| User ID | Stripped entirely, never stored |
| Username / display name | Stripped entirely |
| Channel name | Stripped entirely |
| IP address | Never collected |
| Chat message content | Stripped entirely |
| Config values | Masked to `*` |
| Platform message ID | Stripped entirely |

## Anonymization details

### HMAC account hashing

Account and install IDs are hashed using HMAC-SHA256 with a per-extension salt (auto-generated, not accessible to you). The resulting `anon_*` hashes are:

- **Consistent** — the same account always produces the same hash, so you can group errors by account
- **Not reversible** — you cannot determine which account generated the error
- **Per-extension** — different extensions produce different hashes for the same account

### Error message sanitization

Error messages are sanitized before storage:

- UUIDs matching `[0-9a-f]{8}-...` are replaced with `[UUID]`
- `@username` mentions are replaced with `[USER]`
- URLs containing tokens or auth parameters are replaced with `[URL]`
- Strings longer than 50 characters in `args` are truncated

### Config value masking

Config key names are visible (you defined them in `config_schema`), but all values are masked to `*`. This prevents accidental PII exposure from free-text config fields.

### Error grouping

Errors are grouped by a hash of `handler + sanitized_error_message + first_line_of_stack`. The same error from different accounts and users groups under one entry, with occurrence counts and affected install counts.

## Using error reports for debugging

### Identifying account-specific issues

The `anon_account` hash lets you see error distribution:

```
Error: TypeError: Cannot read property 'balance' of null
  Occurrences: 34
  anon_account anon_a1b2c3: 28 hits
  anon_account anon_x7y8z9: 4 hits
  anon_account anon_m3n4o5: 2 hits
```

28 of 34 errors from the same anonymous account suggests a config-specific issue — perhaps that account has an unusual config combination.

### Identifying platform-specific issues

Filter by platform to see if an error only occurs on a specific chat platform.

### Identifying version-specific issues

The version field shows when an error was introduced. If errors spike after a version release, you can quickly identify the regression.

### Identifying role-specific issues

The user role field (subscriber, moderator, etc.) can reveal issues that only affect certain permission levels.

## Retention

Error reports are retained for 30 days, then automatically deleted.

## Account owner view

Accounts that have your extension installed see their own errors and logs — not anonymized, since it is their own data. This is separate from the developer view:

| View | Who sees it | Anonymized? | Scope |
|------|------------|-------------|-------|
| Developer Error Dashboard | Extension developer | Yes | All installs, all accounts |
| Account Install Logs | Account owner | No (own data) | Only this account's install |

Account owners see their own usernames, chat content, and config values. Extension secrets and API keys are always masked regardless of viewer.

## Accessing error reports

### Developer dashboard

Navigate to your extension in the developer dashboard and open the Errors tab.

### CLI

```bash
lumio logs --level error
```

### API

Error reports are available via the REST API:

```
GET /v1/developer/extensions/{extension_id}/errors?since=2026-05-19T00:00:00Z&handler=points
```

This endpoint requires the `feature:extension_development` feature flag and extension ownership verification.