# discord-bot

`discord-bot` is a Discord slash-command service that talks to
`ha-gateway` over plaintext gRPC and exposes common Home Assistant actions in
Discord.

## How It Works

Runtime flow:

1. The bot starts a Discord session and registers slash commands.
2. A user runs a slash command such as `/light list` or `/light on`.
3. The Discord adapter routes the interaction to the app layer.
4. The app layer calls `ha-gateway` through the secondary gRPC adapter.
5. `ha-gateway` talks to Home Assistant and returns the result.
6. The bot formats the response back into a Discord message.

The service follows the same hexagonal structure as `ha-gateway`:

- `cmd/bot`: process bootstrap
- `internal/adapters/primary/discord`: slash command registration and handlers
- `internal/app`: command orchestration and response formatting
- `internal/adapters/secondary/gateway`: gRPC client for `ha-gateway`
- `internal/core/ports/driven`: app-facing gateway interface
- `internal/config`: env loading
- `internal/telemetry`: OpenTelemetry setup

## Command Behavior

- List commands respond as regular channel messages.
- Action commands use deferred ephemeral replies, then send a follow-up result.
- Light autocomplete is backed by `ListLights` from `ha-gateway`.
- Switch autocomplete support exists in code, but there is currently no switch
  action command that uses it.

## Common Commands

### List lights

```text
/light list
```

Shows all discovered lights in a fixed-width block. Each line includes:

- state emoji: `🟢` on, `🔴` off, `⚠️` unavailable or other state
- friendly name
- raw state
- supported color modes
- kelvin range when available

Example output shape:

```text
🟢 Desk Lamp       on           color_temp,xy 2000-6535K
🔴 Closet          off          hs,color_temp 2202-4000K
⚠️ Hall Group      unavailable  color_temp 2000-6535K hue-group
```

### Turn on a light

```text
/light on light:<entity> brightness:80 color_temp:3000
```

Options:

- `light`: required, autocomplete enabled
- `brightness`: optional, `1-100`
- `color_temp`: optional, `2000-6535`

The bot responds with a confirmation such as:

```text
Turned on `Desk Lamp` (brightness 80%, 3000K).
```

### Turn off a light

```text
/light off light:<entity> transition:3
```

Options:

- `light`: required, autocomplete enabled
- `transition`: optional, `0-30` seconds

### Toggle a light

```text
/light toggle light:<entity>
```

Option:

- `light`: required, autocomplete enabled

### List switches

```text
/switch list
```

Shows discovered switches in a fixed-width block with:

- state emoji
- friendly name
- raw state
- device class

## Configuration

Environment variables:

- `DISCORD_TOKEN`: required Discord bot token
- `GUILD_ID`: optional guild ID; if set, commands are registered to that guild
- `HA_GATEWAY_ADDR`: required gRPC address for `ha-gateway`
- `OTEL_ENDPOINT`: optional OTLP gRPC endpoint; empty disables telemetry

Example env file: [`.env.example`](/Users/nik-macbookair/repo/home-service/discord-bot/.env.example)

## Local Run

Create an env file and fill in real values:

```bash
cp discord-bot/.env.example discord-bot/.env
```

Then run:

```bash
cd discord-bot
go run ./cmd/bot
```

## Build

```bash
cd discord-bot
go build ./...
```

## Docker

Build from the repo root:

```bash
docker build -f discord-bot/Dockerfile -t discord-bot:dev .
```

## Current Limitations

- no switch on/off/toggle command is exposed yet
- the bot depends on `ha-gateway` being reachable and healthy
- list formatting is optimized for monospace code blocks, not rich embeds
- authentication/authorization is whatever Discord and the internal network
  provide; the bot does not add another auth layer itself