diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index bb34617..1e42bca 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -12,7 +12,13 @@ **Delivers:** REQ-01 (send/receive messages), REQ-09 (user ID auth) -**Status:** 🔲 Not started +**Plans:** 2 plans + +Plans: +- [ ] 01-01-PLAN.md — Create Telegram bot and n8n workflow +- [ ] 01-02-PLAN.md — Verify echo and authentication + +**Status:** 🔲 Not started (planned) --- diff --git a/.planning/phases/01-foundation/01-01-PLAN.md b/.planning/phases/01-foundation/01-01-PLAN.md new file mode 100644 index 0000000..370333c --- /dev/null +++ b/.planning/phases/01-foundation/01-01-PLAN.md @@ -0,0 +1,189 @@ +--- +phase: 01-foundation +plan: 01 +type: execute +wave: 1 +depends_on: [] +files_modified: + - n8n-workflow.json +autonomous: false +user_setup: + - service: telegram + why: "Bot token required for n8n Telegram integration" + account_setup: + - task: "Create Telegram bot" + location: "Telegram app -> @BotFather" + steps: + - "Open Telegram, search for @BotFather" + - "Send /newbot" + - "Choose a name (e.g., 'Unraid Docker Manager')" + - "Choose a username (must end with 'bot', e.g., 'unraid_docker_bot')" + - "Copy the API token provided" + env_vars: + - name: TELEGRAM_BOT_TOKEN + source: "BotFather response after /newbot" + - name: TELEGRAM_USER_ID + source: "Send any message to @userinfobot to get your Telegram user ID" + +must_haves: + truths: + - "User can send a message to the Telegram bot" + - "Bot responds only to authorized user ID" + - "Unauthorized users receive no response (silent ignore)" + - "Echo response includes original message and timestamp" + artifacts: + - path: "n8n-workflow.json" + provides: "Complete n8n workflow definition" + contains: "Telegram Trigger" + key_links: + - from: "Telegram Trigger node" + to: "IF node" + via: "message.from.id check" + pattern: "from.id" + - from: "IF node (true branch)" + to: "Code node" + via: "authenticated flow" + - from: "Code node" + to: "Telegram Send node" + via: "echo message" +--- + + +Create the n8n workflow that receives Telegram messages, authenticates the user, and echoes messages back with timestamp. + +Purpose: Establish the foundation for all bot communication - prove the Telegram <-> n8n round-trip works before adding Docker features. +Output: Working n8n workflow that echoes messages back to the authorized user. + + + +@/home/luc/.claude/get-shit-done/workflows/execute-plan.md +@/home/luc/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/ROADMAP.md +@.planning/STATE.md +@.planning/phases/01-foundation/01-CONTEXT.md +@.planning/phases/01-foundation/01-RESEARCH.md + + + + + + Task 1: Create Telegram Bot and Configure n8n + +User must complete external setup before workflow can be created: + +1. **Create Telegram Bot:** + - Open Telegram, search for @BotFather + - Send `/newbot` + - Follow prompts for name (e.g., "Unraid Docker Manager") + - Choose username ending with 'bot' (e.g., "unraid_docker_bot") + - Save the API token provided + +2. **Get Your Telegram User ID:** + - In Telegram, search for @userinfobot + - Send any message + - Note your "Id" value (numeric) + +3. **Configure n8n Environment Variables:** + - Add to n8n container environment: + - `TELEGRAM_BOT_TOKEN=` + - `TELEGRAM_USER_ID=` + - Restart n8n container if needed + +4. **Create Telegram Credential in n8n:** + - n8n UI -> Credentials -> Add -> Telegram API + - Paste bot token in "Access Token" field + - Save credential + + Type "done" when Telegram bot is created and n8n credential is configured + + + + Task 2: Create n8n Workflow for Telegram Echo + n8n-workflow.json + +Create an n8n workflow JSON file with the following structure: + +**Workflow: "Docker Manager Bot"** + +**Node 1: Telegram Trigger** +- Type: n8n-nodes-base.telegramTrigger +- Updates: "message" +- Use the Telegram API credential + +**Node 2: IF (User Authentication)** +- Type: n8n-nodes-base.if +- Condition: `{{ $json.message.from.id.toString() }}` equals `{{ $env.TELEGRAM_USER_ID }}` +- True branch continues to echo +- False branch: no connected nodes (silent ignore) + +**Node 3: Code (Format Echo)** +- Type: n8n-nodes-base.code +- JavaScript code: +```javascript +const message = $input.item.json.message; +const timestamp = new Date().toISOString(); +const text = message.text || '(no text)'; + +return { + json: { + chatId: message.chat.id, + text: `Got: ${text}\n\nProcessed: ${timestamp}` + } +}; +``` + +**Node 4: Telegram (Send Message)** +- Type: n8n-nodes-base.telegram +- Resource: message +- Operation: sendMessage +- Chat ID: `={{ $json.chatId }}` +- Text: `={{ $json.text }}` +- Parse Mode: HTML (for future formatting) + +**Connections:** +- Telegram Trigger -> IF +- IF (true) -> Code +- Code -> Telegram Send +- IF (false) -> (nothing, ends workflow) + +Save as `n8n-workflow.json` in the project root. This file can be imported into n8n. + +**Important:** The workflow JSON should be valid for n8n import. Include proper node positions for visual layout. + + +- File `n8n-workflow.json` exists +- JSON is valid (parse without errors) +- Contains all 4 nodes: telegramTrigger, if, code, telegram +- IF condition references `$env.TELEGRAM_USER_ID` + + +- n8n workflow JSON file created and valid +- All nodes properly connected +- User ID authentication configured via environment variable + + + + + + +1. Workflow JSON file exists at project root +2. JSON parses without errors +3. All required nodes present with correct types +4. IF node checks user ID from environment variable +5. Code node includes timestamp in output + + + +- n8n-workflow.json exists and is valid JSON +- Workflow includes Telegram Trigger, IF (auth), Code (echo), Telegram Send +- Authentication uses environment variable for user ID +- Silent ignore implemented (no nodes on false branch) + + + +After completion, create `.planning/phases/01-foundation/01-01-SUMMARY.md` + diff --git a/.planning/phases/01-foundation/01-02-PLAN.md b/.planning/phases/01-foundation/01-02-PLAN.md new file mode 100644 index 0000000..7f585a3 --- /dev/null +++ b/.planning/phases/01-foundation/01-02-PLAN.md @@ -0,0 +1,122 @@ +--- +phase: 01-foundation +plan: 02 +type: execute +wave: 2 +depends_on: ["01-01"] +files_modified: [] +autonomous: false + +must_haves: + truths: + - "Message sent to bot receives echo response" + - "Echo includes original message text" + - "Echo includes processing timestamp" + - "Different Telegram user receives no response" + artifacts: [] + key_links: + - from: "User Telegram message" + to: "n8n workflow" + via: "Telegram webhook" + - from: "n8n workflow" + to: "User Telegram" + via: "Telegram Bot API sendMessage" +--- + + +Import the workflow into n8n and verify end-to-end Telegram communication works. + +Purpose: Confirm the foundation is solid before building Docker features on top. +Output: Verified working bot that echoes messages to authorized user only. + + + +@/home/luc/.claude/get-shit-done/workflows/execute-plan.md +@/home/luc/.claude/get-shit-done/templates/summary.md + + + +@.planning/PROJECT.md +@.planning/phases/01-foundation/01-01-SUMMARY.md +@n8n-workflow.json + + + + + + Task 1: Import and Activate Workflow in n8n + +Import the workflow JSON into n8n: + +1. Open n8n UI +2. Go to Workflows -> Import from File +3. Select `n8n-workflow.json` from the project +4. Review the imported workflow +5. Ensure Telegram credential is selected in Telegram nodes +6. Activate the workflow (toggle on) + + Type "activated" when workflow is imported and active in n8n + + + + Task 2: Verify Authorized User Echo + Telegram bot that echoes messages back with timestamp + +1. Open Telegram +2. Find your bot (search for the username you created) +3. Send a test message: "Hello bot!" +4. Verify you receive a response like: + ``` + Got: Hello bot! + + Processed: 2026-01-28T12:34:56.789Z + ``` +5. The timestamp should be within seconds of when you sent the message +6. Try another message to confirm consistency + + Type "working" if echo works correctly, or describe any issues + + + + Task 3: Verify Unauthorized User Blocked + Silent ignore for unauthorized Telegram users + +**Option A (if you have another device/account):** +1. From a different Telegram account, send a message to the bot +2. Verify NO response is received (bot appears offline) +3. Wait 30 seconds to confirm silence + +**Option B (if only one account):** +1. Temporarily change TELEGRAM_USER_ID in n8n to a wrong value +2. Restart n8n +3. Send a message to the bot +4. Verify NO response +5. Restore correct TELEGRAM_USER_ID +6. Restart n8n +7. Verify echo works again + +The bot should give no indication it received the message from unauthorized users. + + Type "secure" if unauthorized users are blocked, or describe any issues + + + + + +1. Workflow imported and active in n8n +2. Authorized user receives echo with timestamp +3. Unauthorized user receives no response +4. Bot responds within a few seconds + + + +- Telegram message to bot receives echo response +- Echo includes original message and timestamp +- Unauthorized users get silent ignore (no response) +- REQ-01 (send/receive messages) validated +- REQ-09 (user ID auth) validated + + + +After completion, create `.planning/phases/01-foundation/01-02-SUMMARY.md` +