{"id":36500472,"url":"https://github.com/h4ks-com/hanna","last_synced_at":"2026-01-12T02:20:15.974Z","repository":{"id":311694952,"uuid":"1044621793","full_name":"h4ks-com/hanna","owner":"h4ks-com","description":"Build sophisticated IRC bots using n8n's visual interface - no coding required","archived":false,"fork":false,"pushed_at":"2025-09-21T21:26:01.000Z","size":15306,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-30T04:54:19.755Z","etag":null,"topics":["ai","ai-agents","automation","h4ks","homelab","integration","irc","irc-bot","n8n","n8n-community-node-package","workflow","workflow-automation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/h4ks-com.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-26T01:07:38.000Z","updated_at":"2025-09-18T03:57:46.000Z","dependencies_parsed_at":"2025-08-26T03:26:47.204Z","dependency_job_id":"38af693d-9c70-42e4-9201-465b9370c9c6","html_url":"https://github.com/h4ks-com/hanna","commit_stats":null,"previous_names":["h4ks-com/hanna"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/h4ks-com/hanna","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4ks-com%2Fhanna","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4ks-com%2Fhanna/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4ks-com%2Fhanna/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4ks-com%2Fhanna/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/h4ks-com","download_url":"https://codeload.github.com/h4ks-com/hanna/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/h4ks-com%2Fhanna/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28331993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T00:36:25.062Z","status":"online","status_checked_at":"2026-01-12T02:00:08.677Z","response_time":98,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","automation","h4ks","homelab","integration","irc","irc-bot","n8n","n8n-community-node-package","workflow","workflow-automation"],"created_at":"2026-01-12T02:20:15.825Z","updated_at":"2026-01-12T02:20:15.968Z","avatar_url":"https://github.com/h4ks-com.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Hanna - IRC Bot with REST API\n\n[![npm version](https://badge.fury.io/js/n8n-nodes-hanna.svg)](https://www.npmjs.com/package/n8n-nodes-hanna)\n\nA robust, self-contained Go IRC bot that connects over TLS and exposes a secure, token-authenticated REST API for remote control. Perfect for automation, monitoring, and integration with other services.\n\n## 🚀 Features\n\n- **Secure IRC Connection**: TLS-enabled IRC connections with optional server password support\n- **SASL Authentication**: Optional SASL PLAIN authentication for IRC networks that require it\n- **Auto-Reconnect**: Intelligent reconnection with exponential backoff for maximum uptime\n- **REST API**: Token-protected HTTP/HTTPS endpoints for complete bot control\n- **IRC Network Discovery**: List channels and get user information via LIST and WHOIS commands\n- **Flexible Event System**: Advanced trigger system supporting multiple IRC events (mentions, joins, parts, mode changes, etc.)\n- **n8n Integration**: Comprehensive n8n node package with both action and trigger nodes\n- **Multiple Webhooks**: Support for multiple trigger endpoints with filtering and authentication\n- **Channel Management**: Join, part, and track channels programmatically\n- **Message Control**: Send messages, notices, and raw IRC commands via API\n- **Graceful Shutdown**: Clean disconnection and resource cleanup\n- **Zero Dependencies**: Self-contained binary with no external dependencies\n- **Production Ready**: Comprehensive logging, error handling, and monitoring endpoints\n\n## 📋 Requirements\n\n- Go 1.24 or later\n- IRC server with TLS support\n- (Optional) TLS certificates for HTTPS API\n\n## 🛠️ Installation\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/h4ks-com/hanna\ncd hanna\n\n# Build from source (no need for go mod tidy - dependencies are all local)\ngo build -o hanna .\n\n# Or build with specific flags for production\nCGO_ENABLED=0 go build -ldflags=\"-w -s\" -o hanna .\n```\n\n### Docker Build\n\n```bash\n# Build using Docker\ndocker build -t hanna-bot .\n\n# Or using docker-compose\ndocker-compose build hanna-bot\n```\n\n### Project Structure\n\nThe project is organized as a proper Go module:\n```\nhanna/\n├── main.go              # Main application entry point\n├── irc/                 # IRC client package\n│   ├── client.go        # IRC client implementation\n│   └── *_test.go        # Tests for IRC functionality\n├── go.mod               # Go module definition\n└── Dockerfile           # Docker build configuration\n```\n\n### Quick Start\n\n```bash\n# Basic setup with HTTP API\nAPI_TOKEN=your_secret_token \\\nIRC_ADDR=irc.libera.chat:6697 \\\nIRC_NICK=YourBotName \\\n./hanna\n```\n\n## ⚙️ Configuration\n\nAll configuration is done via environment variables:\n\n### IRC Configuration\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `IRC_ADDR` | IRC server address (host:port) | - | ✅ |\n| `IRC_TLS` | Enable TLS connection | `1` | ❌ |\n| `IRC_TLS_INSECURE` | Skip TLS certificate verification | `0` | ❌ |\n| `IRC_PASS` | Server password | - | ❌ |\n| `IRC_NICK` | Bot nickname | `goircbot` | ❌ |\n| `IRC_USER` | Username/ident | `goircbot` | ❌ |\n| `IRC_NAME` | Real name/GECOS | `Go IRC Bot` | ❌ |\n| `SASL_USER` | SASL authentication username | - | ❌ |\n| `SASL_PASS` | SASL authentication password | - | ❌ |\n| `AUTOJOIN` | Comma-separated channels to auto-join | - | ❌ |\n\n### API Configuration\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `API_ADDR` | HTTP/HTTPS listen address | `:8080` | ❌ |\n| `API_TOKEN` | Bearer token for API authentication | - | ⚠️ |\n| `API_TLS` | Enable HTTPS | `0` | ❌ |\n| `API_CERT` | Path to TLS certificate file | - | ⚠️* |\n| `API_KEY` | Path to TLS private key file | - | ⚠️* |\n\n### n8n Integration\n\n| Variable | Description | Default | Required |\n|----------|-------------|---------|----------|\n| `N8N_WEBHOOK` | Legacy webhook URL for chat integration | - | ❌ |\n| `TRIGGER_CONFIG` | JSON configuration for multiple trigger endpoints | - | ❌ |\n\n### Event Trigger Configuration\n\nThe bot supports a flexible trigger system for sending IRC events to multiple endpoints:\n\n**Legacy Mode (backward compatible):**\n```bash\nexport N8N_WEBHOOK=\"https://n8n.example.com/webhook/irc-bot\"\n```\n\n**Advanced Mode (recommended):**\n```bash\nexport TRIGGER_CONFIG='{\n  \"endpoints\": {\n    \"mentions\": {\n      \"url\": \"https://n8n.example.com/webhook/mentions\",\n      \"token\": \"secret-token-123\",\n      \"events\": [\"mention\"],\n      \"channels\": [\"#support\", \"#general\"]\n    },\n    \"moderation\": {\n      \"url\": \"https://n8n.example.com/webhook/moderation\", \n      \"token\": \"mod-token-456\",\n      \"events\": [\"join\", \"part\", \"kick\", \"mode\"],\n      \"channels\": [\"#general\"]\n    }\n  }\n}'\n```\n\n**Supported Event Types:**\n- `mention` - When the bot is mentioned\n- `privmsg` - All channel/private messages\n- `join` - User joins a channel\n- `part` - User leaves a channel  \n- `quit` - User quits IRC\n- `kick` - User is kicked from channel\n- `mode` - Mode changes (op, voice, etc.)\n- `nick` - Nickname changes\n- `topic` - Channel topic changes\n- `notice` - IRC notices\n\n*Required when `API_TLS=1`  \n⚠️ Highly recommended for security\n\n## 🔒 HTTPS Setup\n\n### Using Let's Encrypt\n\nIf you have Let's Encrypt certificates for your domain:\n\n```bash\nexport API_TLS=1\nexport API_CERT=/etc/letsencrypt/live/yourdomain.com/fullchain.pem\nexport API_KEY=/etc/letsencrypt/live/yourdomain.com/privkey.pem\n```\n\n### Self-Signed Certificates (Development)\n\n```bash\n# Generate self-signed certificate\nopenssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes\n\n# Use with bot\nexport API_TLS=1\nexport API_CERT=cert.pem\nexport API_KEY=key.pem\n```\n\n## 🌐 API Reference\n\n### Authentication\n\nAll API endpoints (except `/health`) require a Bearer token:\n\n```bash\ncurl -H \"Authorization: Bearer your_secret_token\" https://your-server:8080/api/state\n```\n\n### Endpoints\n\n#### Health Check\n```http\nGET /health\n```\nReturns bot connection status and current nickname.\n\n**Response:**\n```json\n{\n  \"ok\": true,\n  \"nick\": \"YourBot\"\n}\n```\n\n#### Bot State\n```http\nGET /api/state\nAuthorization: Bearer \u003ctoken\u003e\n```\nReturns comprehensive bot status including connected channels.\n\n**Response:**\n```json\n{\n  \"connected\": true,\n  \"nick\": \"YourBot\",\n  \"channels\": [\"#general\", \"#bots\"]\n}\n```\n\n#### Join Channel\n```http\nPOST /api/join\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"channel\": \"#example\"\n}\n```\n\n#### Leave Channel\n```http\nPOST /api/part\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"channel\": \"#example\",\n  \"reason\": \"Goodbye!\"\n}\n```\n\n#### Send Message\n```http\nPOST /api/send\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"target\": \"#example\",\n  \"message\": \"Hello, world!\"\n}\n```\n\n#### Send Notice\n```http\nPOST /api/notice\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"target\": \"#example\",\n  \"message\": \"This is a notice\"\n}\n```\n\n#### Change Nickname\n```http\nPOST /api/nick\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"nick\": \"NewBotName\"\n}\n```\n\n#### Send Raw IRC Command\n```http\nPOST /api/raw\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"line\": \"PRIVMSG #channel :Custom message\"\n}\n```\n\n#### List IRC Channels\n```http\nGET /api/list\nAuthorization: Bearer \u003ctoken\u003e\n```\n\nResponse:\n```json\n{\n  \"channels\": [\n    {\n      \"channel\": \"#general\",\n      \"users\": \"42\",\n      \"topic\": \"Welcome to the general discussion channel\"\n    },\n    {\n      \"channel\": \"#bots\",\n      \"users\": \"15\", \n      \"topic\": \"Bot testing and development\"\n    }\n  ],\n  \"count\": 2\n}\n```\n\n#### Get User Information (WHOIS)\n```http\nPOST /api/whois\nAuthorization: Bearer \u003ctoken\u003e\nContent-Type: application/json\n\n{\n  \"nick\": \"username\"\n}\n```\n\nResponse:\n```json\n{\n  \"nick\": \"username\",\n  \"user\": \"user\",\n  \"host\": \"example.com\",\n  \"real_name\": \"Real Name\",\n  \"server\": \"irc.libera.chat\",\n  \"server_info\": \"Stockholm, Sweden\",\n  \"operator\": false,\n  \"idle_seconds\": \"42\",\n  \"idle_info\": \"seconds idle\",\n  \"channels\": \"@#ops +#general #random\",\n  \"raw_data\": [\n    {\n      \"type\": \"user\",\n      \"nick\": \"username\",\n      \"user\": \"user\",\n      \"host\": \"example.com\",\n      \"real_name\": \"Real Name\"\n    }\n  ]\n}\n```\n\n## 📝 Usage Examples\n\n### Basic Bot Setup\n\n```bash\n#!/bin/bash\n\n# Production setup with HTTPS and advanced n8n trigger integration\nexport API_TOKEN=\"$(openssl rand -hex 32)\"\nexport API_TLS=1\nexport API_CERT=\"/etc/letsencrypt/live/bot.example.com/fullchain.pem\"\nexport API_KEY=\"/etc/letsencrypt/live/bot.example.com/privkey.pem\"\nexport API_ADDR=\":443\"\n\nexport IRC_ADDR=\"irc.libera.chat:6697\"\nexport IRC_NICK=\"MyAwesomeBot\"\nexport IRC_USER=\"mybot\"\nexport IRC_NAME=\"My Awesome IRC Bot\"\nexport AUTOJOIN=\"#general,#bots\"\n\n# Advanced trigger configuration for multiple n8n workflows\nexport TRIGGER_CONFIG='{\n  \"endpoints\": {\n    \"mentions\": {\n      \"url\": \"https://n8n.example.com/webhook/bot-mentions\",\n      \"token\": \"mention-token-123\",\n      \"events\": [\"mention\"],\n      \"channels\": [\"#general\", \"#support\"]\n    },\n    \"moderation\": {\n      \"url\": \"https://n8n.example.com/webhook/moderation\",\n      \"token\": \"mod-token-456\", \n      \"events\": [\"join\", \"part\", \"kick\", \"mode\"],\n      \"channels\": [\"#general\"]\n    },\n    \"private-messages\": {\n      \"url\": \"https://n8n.example.com/webhook/private-chat\",\n      \"token\": \"private-token-789\",\n      \"events\": [\"privmsg\"],\n      \"channels\": []\n    }\n  }\n}'\n\n./hanna\n```\n\n### n8n Integration \u0026 Event Triggers\n\nThe bot provides comprehensive integration with n8n through both legacy webhooks and the new trigger system.\n\n#### Legacy Webhook Integration (Simple)\n\nWhen someone mentions the bot in IRC with `@botname message`, the bot will automatically call the configured n8n webhook:\n\n```json\n{\n  \"eventType\": \"mention\",\n  \"sender\": \"username\",\n  \"target\": \"#channel\", \n  \"message\": \"hello bot\",\n  \"chatInput\": \"@botname hello bot\",\n  \"botNick\": \"MyAwesomeBot\",\n  \"sessionId\": \"IRC\",\n  \"timestamp\": 1692345678,\n  \"messageTags\": {\n    \"time\": \"2023-09-01T12:00:00.000Z\"\n  }\n}\n```\n\n#### Advanced Trigger System (Recommended)\n\nThe new trigger system supports multiple IRC events and endpoints:\n\n**1. Install the n8n Node Package**\n\n```bash\n# In your n8n installation\nnpm install n8n-nodes-hanna\n```\n\n**2. Create Trigger Workflows**\n\n- Add \"Hanna Bot Trigger\" nodes to your workflows\n- Configure authentication tokens and event filters\n- Copy webhook URLs to your `TRIGGER_CONFIG`\n\n**3. Event Examples:**\n\n**User Joins Channel:**\n```json\n{\n  \"eventType\": \"join\",\n  \"sender\": \"newuser\",\n  \"target\": \"#general\",\n  \"message\": \"\",\n  \"botNick\": \"MyBot\",\n  \"timestamp\": 1692345678\n}\n```\n\n**Channel Mode Change:**\n```json\n{\n  \"eventType\": \"mode\", \n  \"sender\": \"operator\",\n  \"target\": \"#general\",\n  \"message\": \"Mode #general +o newop\",\n  \"timestamp\": 1692345678\n}\n```\n\n**Private Message:**\n```json\n{\n  \"eventType\": \"privmsg\",\n  \"sender\": \"user123\",\n  \"target\": \"MyBot\",\n  \"message\": \"Hello bot, how are you?\",\n  \"chatInput\": \"Hello bot, how are you?\",\n  \"timestamp\": 1692345678\n}\n```\n\n#### Example n8n Workflow Setup\n\n**Using the New Trigger Node (Recommended):**\n\n1. Install `n8n-nodes-hanna` package in your n8n instance\n2. Create a new workflow in n8n\n3. Add a \"Hanna Bot Trigger\" node\n4. Configure:\n   - Authentication token (create a secure random token)\n   - Select events you want to monitor (mention, join, part, etc.)\n   - Optional: Filter by channels or users\n5. Copy the webhook URL from the trigger node\n6. Add the URL and token to your bot's `TRIGGER_CONFIG`\n7. Add processing nodes (OpenAI, database, notifications, etc.)\n8. Optionally add \"Hanna Bot\" action node to send responses back to IRC\n\n**Using Legacy Webhook:**\n\n1. Create a new workflow in n8n\n2. Add a \"Webhook\" trigger node  \n3. Set the webhook URL in the `N8N_WEBHOOK` environment variable\n4. Process the incoming IRC data and respond as needed\n5. Optionally use the Hanna API to send responses back to IRC\n\n#### Advanced Workflow Examples\n\n**AI-Powered Chat Bot:**\n```\nHanna Bot Trigger (mention events) \n  → OpenAI Chat Completion\n  → Hanna Bot Send Message\n```\n\n**Channel Moderation:**\n```\nHanna Bot Trigger (kick, mode events)\n  → Log to Database\n  → Send Alert if Spam Detected\n  → Auto-Ban Repeat Offenders\n```\n\n**Welcome System:**\n```  \nHanna Bot Trigger (join events)\n  → Check User Database\n  → Send Welcome Message for New Users\n  → Assign Roles Based on Rules\n```\n\n**Multi-Channel Bot:**\n```\nTrigger 1: Support Channel (mention, privmsg in #support)\n  → Route to Support AI\n  → Log Support Ticket\n  \nTrigger 2: General Chat (mention in #general)  \n  → Route to Fun AI\n  → Random Responses\n```\n\n**Mention Examples:**\n- `@MyAwesomeBot what's the weather?` → Triggers mention event\n- `@MyAwesomeBot help` → Triggers mention event  \n- `MyAwesomeBot hello` → Does NOT trigger mention (missing @)\n- `@DifferentBot hello` → Does NOT trigger mention (wrong bot name)\n\n**Other Event Examples:**\n- User joins `#general` → Triggers join event  \n- User types `hello everyone` in `#general` → Triggers privmsg event\n- Operator gives voice to user → Triggers mode event\n- User gets kicked from channel → Triggers kick event\n\n### Send Message via API\n\n```bash\n# Send a message to a channel\ncurl -X POST \\\n  -H \"Authorization: Bearer your_secret_token\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"target\": \"#general\", \"message\": \"Hello from the API!\"}' \\\n  https://bot.example.com/api/send\n\n# Check bot status\ncurl -H \"Authorization: Bearer your_secret_token\" \\\n  https://bot.example.com/api/state\n\n# Join a new channel\ncurl -X POST \\\n  -H \"Authorization: Bearer your_secret_token\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"channel\": \"#newchannel\"}' \\\n  https://bot.example.com/api/join\n```\n\n### Integration Examples\n\n#### Python Integration\n\n```python\nimport requests\nimport json\n\nclass IRCBotAPI:\n    def __init__(self, base_url, token):\n        self.base_url = base_url.rstrip('/')\n        self.headers = {\n            'Authorization': f'Bearer {token}',\n            'Content-Type': 'application/json'\n        }\n    \n    def send_message(self, target, message):\n        data = {'target': target, 'message': message}\n        response = requests.post(\n            f'{self.base_url}/api/send',\n            headers=self.headers,\n            json=data\n        )\n        return response.json()\n    \n    def get_status(self):\n        response = requests.get(\n            f'{self.base_url}/api/state',\n            headers=self.headers\n        )\n        return response.json()\n\n# Usage\nbot = IRCBotAPI('https://bot.example.com', 'your_secret_token')\nbot.send_message('#general', 'Hello from Python!')\nstatus = bot.get_status()\nprint(f\"Bot is {'connected' if status['connected'] else 'disconnected'}\")\n```\n\n#### Shell Script Integration\n\n```bash\n#!/bin/bash\n\nBOT_URL=\"https://bot.example.com\"\nBOT_TOKEN=\"your_secret_token\"\n\nsend_irc_message() {\n    local channel=\"$1\"\n    local message=\"$2\"\n    \n    curl -s -X POST \\\n        -H \"Authorization: Bearer $BOT_TOKEN\" \\\n        -H \"Content-Type: application/json\" \\\n        -d \"{\\\"target\\\": \\\"$channel\\\", \\\"message\\\": \\\"$message\\\"}\" \\\n        \"$BOT_URL/api/send\"\n}\n\n# Send system status to IRC\nLOAD=$(uptime | awk -F'load average:' '{print $2}')\nsend_irc_message \"#monitoring\" \"Server load: $LOAD\"\n```\n\n## 🐳 Docker Deployment\n\n### Quick Start with Docker Compose\n\nThe easiest way to run Hanna is using Docker Compose with the included configuration:\n\n1. **Copy environment template:**\n   ```bash\n   cp .env.example .env\n   ```\n\n2. **Configure your bot:**\n   Edit `.env` and set at least:\n   ```bash\n   IRC_ADDR=irc.libera.chat:6697\n   IRC_NICK=YourBotName\n   API_TOKEN=your-secure-token-here\n   AUTOJOIN=#your-channels\n   ```\n\n3. **Start the services:**\n   ```bash\n   docker compose up -d\n   ```\n\nThis will start both Hanna IRC bot and n8n for workflow automation. The bot will be available at `http://localhost:8080` and n8n at `http://localhost:5678`.\n\n### Docker Compose Configuration\n\nThe included `compose.yaml` provides:\n\n- **Hanna IRC Bot**: Main bot service with API\n- **n8n**: Workflow automation platform for chat processing\n- **n8n Workflow Loader**: Sidecar container that automatically loads workflows on startup\n- **Automatic networking**: Bot can communicate with n8n via `http://n8n:5678`\n- **Persistent storage**: n8n workflows and data are preserved\n- **Environment-based config**: All settings from `.env` file\n\n### Automatic Workflow Loading\n\nThe Docker Compose setup includes a workflow loader that automatically imports workflows into n8n:\n\n1. **Default Echo Bot**: A pre-configured workflow that echoes IRC messages\n2. **Auto-Import**: Workflows in `n8n-workflow-loader/workflows/` are loaded on startup\n3. **Skip Existing**: Already-imported workflows are detected and skipped\n4. **Auto-Activation**: Imported workflows are automatically activated\n5. **Trigger Integration**: The bot's `TRIGGER_CONFIG` is automatically configured\n\n**Adding Custom Workflows:**\n1. Place workflow JSON files in `n8n-workflow-loader/workflows/`\n2. Remove the `id` field from the workflow JSON\n3. Restart with `docker-compose up -d`\n\nThe workflow loader uses the n8n REST API and includes error handling and duplicate detection.\n\n### Manual Docker Build\n\nIf you prefer to build and run manually:\n\n```bash\n# Build the image\ndocker build -t hanna-bot .\n\n# Run with environment variables\ndocker run -d \\\n  --name hanna \\\n  -p 8080:8080 \\\n  -e API_TOKEN=your_secret_token \\\n  -e IRC_ADDR=irc.libera.chat:6697 \\\n  -e IRC_NICK=DockerBot \\\n  -e AUTOJOIN=\"#general,#bots\" \\\n  hanna-bot\n```\n\n## 🔧 Systemd Service\n\nCreate `/etc/systemd/system/hanna.service`:\n\n```ini\n[Unit]\nDescription=Hanna IRC Bot\nAfter=network.target\n\n[Service]\nType=simple\nUser=ircd\nGroup=ircd\nWorkingDirectory=/opt/hanna\nExecStart=/opt/hanna/hanna\nEnvironmentFile=/opt/hanna/.env\nRestart=always\nRestartSec=10\n\n[Install]\nWantedBy=multi-user.target\n```\n\nEnvironment file `/opt/hanna/.env`:\n\n```bash\nAPI_TOKEN=your_secret_token\nAPI_TLS=1\nAPI_CERT=/etc/letsencrypt/live/bot.example.com/fullchain.pem\nAPI_KEY=/etc/letsencrypt/live/bot.example.com/privkey.pem\nIRC_ADDR=irc.libera.chat:6697\nIRC_NICK=HannaBot\nAUTOJOIN=#general\n\n# Advanced trigger configuration\nTRIGGER_CONFIG={\"endpoints\":{\"mentions\":{\"url\":\"https://n8n.example.com/webhook/mentions\",\"token\":\"secure-token-123\",\"events\":[\"mention\"],\"channels\":[\"#general\",\"#support\"]},\"moderation\":{\"url\":\"https://n8n.example.com/webhook/moderation\",\"token\":\"mod-token-456\",\"events\":[\"join\",\"part\",\"kick\",\"mode\"],\"channels\":[\"#general\"]}}}\n```\n\nEnable and start:\n\n```bash\nsudo systemctl enable hanna\nsudo systemctl start hanna\nsudo systemctl status hanna\n```\n\n## 📊 Monitoring\n\n### Health Check Endpoint\n\nThe `/health` endpoint provides a simple way to monitor bot status:\n\n```bash\n# Check if bot is connected\ncurl -f https://bot.example.com/health || echo \"Bot is down!\"\n```\n\n### Prometheus Metrics (Future Enhancement)\n\nConsider extending the bot with Prometheus metrics for comprehensive monitoring.\n\n## 🛡️ Security Considerations\n\n1. **API Token**: Use a strong, randomly generated token\n2. **HTTPS**: Always use HTTPS in production\n3. **Firewall**: Restrict API access to trusted networks\n4. **File Permissions**: Protect certificate files (0600 permissions)\n5. **Regular Updates**: Keep dependencies and certificates updated\n\n## 📦 n8n Node Package\n\nHanna includes a comprehensive n8n node package (`n8n-nodes-hanna`) that provides both action and trigger nodes for complete IRC automation.\n\n### Installation\n\n```bash\n# Install in your n8n instance\nnpm install n8n-nodes-hanna\n\n# Or install globally\nnpm install -g n8n-nodes-hanna\n```\n\n### Available Nodes\n\n#### 1. Hanna Bot (Action Node)\n- Send messages and notices to IRC channels\n- Join and part channels programmatically  \n- Change bot nickname\n- Send raw IRC commands\n- Get bot status and connected channels\n\n#### 2. Hanna Bot Trigger (Trigger Node)\n- Webhook-based trigger for IRC events\n- Configurable event filtering (mention, join, part, etc.)\n- Channel and user filtering\n- Authentication token validation\n- Support for multiple simultaneous triggers\n\n### Node Configuration\n\n#### Action Node Setup:\n1. Add \"Hanna Bot\" node to your workflow\n2. Configure credentials:\n   - API URL: `https://your-bot.example.com`\n   - API Token: Your bot's API token\n3. Select operation (Send Message, Join Channel, etc.)\n4. Configure target and message parameters\n\n#### Trigger Node Setup:\n1. Add \"Hanna Bot Trigger\" node to your workflow\n2. Set authentication token (secure random string)\n3. Select IRC events to monitor\n4. Optional: Set channel/user filters\n5. Copy webhook URL to bot's `TRIGGER_CONFIG`\n\n### Example Workflows\n\nSee the [Advanced Workflow Examples](#advanced-workflow-examples) section above for complete workflow configurations using both trigger and action nodes.\n\n## 🧪 Testing\n\n```bash\n# Run all tests\ngo test -v\n```\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Run `go test -v` to ensure all tests pass\n6. Submit a pull request\n\n## 📄 License\n\nThis project is licensed under the GPLv3 License - see the LICENSE file for details.\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Bot won't connect to IRC:**\n- Check `IRC_ADDR` format (must include port)\n- Verify TLS settings match server requirements\n- Check firewall/network connectivity\n\n**API returns 401 Unauthorized:**\n- Verify `API_TOKEN` is set and matches request\n- Check `Authorization` header format: `Bearer \u003ctoken\u003e`\n\n**HTTPS certificate errors:**\n- Verify certificate and key file paths\n- Check file permissions\n- Ensure certificate is valid and not expired\n\n**Bot keeps reconnecting:**\n- Check IRC server logs for connection issues\n- Verify SASL credentials if using authentication\n- Check for nick conflicts\n\n### Debug Mode\n\nFor detailed logging, you can modify the log level in the source code or redirect output:\n\n```bash\n./hanna 2\u003e\u00261 | tee bot.log\n```\n\n---\n\n*Built with ❤️ in Go*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh4ks-com%2Fhanna","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fh4ks-com%2Fhanna","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fh4ks-com%2Fhanna/lists"}