KfChatDotNet/README.md

KfChatDotNet

⚠️ IMPORTANT: Read This First ⚠️

If you're contributing to this project, please read PRIVACY.md to learn how to protect your identity.

---

A C# .NET chat bot for KiwiFarms (Sneedchat) with extensive third-party integrations for stream monitoring, gambling site tracking, and interactive commands.

Features

• 🤖 Interactive Chat Bot - Command-based interactions with regex pattern matching
• 🎰 Kasino System - Internal gambling games (mines, limbo, coinflip, blackjack, roulette, and more)
• 📺 Stream Monitoring - Track streams across Twitch, Kick, DLive, PeerTube, Owncast, YouTube
• 💬 Multi-Platform Integration - Discord relay, Twitch chat, Kick events
• 🎲 Gambling Tracking - Monitor bets across Rainbet, Shuffle, Howlgg, Chips.gg, Clash.gg, and more
• 🔄 Auto-Reconnect - Robust WebSocket connection with automatic cookie refresh
• 🗃️ Database-Backed Settings - SQLite database with EF Core migrations

Prerequisites

• .NET 10.0 SDK or higher
• A KiwiFarms account
• (Optional) SQLite viewer for database inspection

Quick Start

1. Clone and Build

git clone <repository-url>
cd KfChatDotNet
dotnet build

2. Configure Credentials

The bot uses a database-backed settings system. On first run, it will create db.sqlite with default settings.

Option A: Using config.json (Easiest for First Run)

Create KfChatDotNetBot/config.json:

{
  "KfUsername": "your_kiwifarms_username",
  "KfPassword": "your_kiwifarms_password",
  "KfChatRoomId": 15,
  "KfDomain": "kiwifarms.st",
  "KfWsEndpoint": "wss://kiwifarms.st:9443/chat.ws",
  "SuppressChatMessages": true
}

Note: The bot will automatically migrate config.json to the database on first run and rename it to config.json.migrated.

Option B: Directly Edit Database (After First Run)

Build the project, then run the bot once. This generates tables which can be updated by running sqlite:

# Build
dotnet build

# Run
dotnet run --project KfChatDotNetBot

# Ctr + C to stop the application, then run
sqlite3 db.sqlite

-- Update your credentials
UPDATE Settings SET Value = 'your_username' WHERE Key = 'KiwiFarms.Username';
UPDATE Settings SET Value = 'your_password' WHERE Key = 'KiwiFarms.Password';

-- Enable read-only mode for testing
UPDATE Settings SET Value = 'true' WHERE Key = 'KiwiFarms.SuppressChatMessages';

3. Run the Bot

cd KfChatDotNetBot
dotnet run

The bot will:

1. ✅ Create/migrate the database
2. ✅ Sync built-in settings
3. ✅ Connect to KiwiFarms chat
4. ✅ Start listening for commands

Configuration Guide

Essential Settings

Setting	Description	Default	Required
KiwiFarms.Username	Your KF username	-	✅ Yes
KiwiFarms.Password	Your KF password	-	✅ Yes
KiwiFarms.RoomId	Chat room ID to join	15	✅ Yes
KiwiFarms.SuppressChatMessages	Read-only mode (no messages sent)	false	Recommended for testing

Optional Integrations

All external services are disabled by default or optional:

Service	Enable Setting	Auth Required
Discord	Discord.Token	Bot token
Kick	Kick.Enabled	None (public API)
Twitch	Auto-enabled	None (public GraphQL)
Jackpot	Jackpot.Enabled	None
Rainbet	Rainbet.Enabled	None
Shuffle	Auto-enabled	None
YouTube	YouTube.ApiKey	API key
FlareSolverr	FlareSolverr.ApiUrl	Service URL

Viewing All Settings

# View non-secret settings
sqlite3 db.sqlite "SELECT Key, Value, Description FROM Settings WHERE IsSecret = 0 LIMIT 20;"

# View secret settings (passwords, tokens)
sqlite3 db.sqlite "SELECT Key, Value FROM Settings WHERE IsSecret = 1;"

Testing Mode

For safe testing without sending messages to chat:

UPDATE Settings SET Value = 'true' WHERE Key = 'KiwiFarms.SuppressChatMessages';

When enabled, the bot will connect, listen, and process commands but won't actually send messages.

Development

Project Structure

KfChatDotNet/
├── KfChatDotNetWsClient/     # WebSocket client library for KF chat
├── KickWsClient/             # WebSocket client library for Kick
└── KfChatDotNetBot/          # Main bot application
    ├── Commands/             # Bot commands (implement ICommand)
    ├── Services/             # External service integrations
    ├── Models/               # Data models and DTOs
    ├── Migrations/           # EF Core database migrations
    └── Settings/             # Settings system

Common Commands

# Build the solution
dotnet build

# Run in release mode
dotnet run --project KfChatDotNetBot -c Release

# Clean build artifacts
dotnet clean

# Add a database migration
dotnet ef migrations add MigrationName --project KfChatDotNetBot

# Update database to latest migration
dotnet ef database update --project KfChatDotNetBot

# View migration SQL
dotnet ef migrations script --project KfChatDotNetBot

Adding a New Command

1. Create a class in KfChatDotNetBot/Commands/ implementing ICommand
2. Define regex patterns and command logic
3. The bot auto-discovers commands via reflection on startup

Example:

public class HelloCommand : ICommand
{
    public List<Regex> Patterns => [new Regex(@"^hello$", RegexOptions.IgnoreCase)];
    public string? HelpText => "Says hello!";
    public UserRight RequiredRight => UserRight.User;
    public TimeSpan Timeout => TimeSpan.FromSeconds(10);
    public RateLimitOptionsModel? RateLimitOptions => null;

    public async Task RunCommand(ChatBot botInstance, MessageModel message,
        UserDbModel user, GroupCollection arguments, CancellationToken ctx)
    {
        botInstance.SendChatMessage($"Hello, @{message.Author.Username}!");
    }
}

Database Migrations

Migrations run automatically on startup. The database schema is managed via Entity Framework Core.

# Create a new migration
dotnet ef migrations add AddNewFeature --project KfChatDotNetBot

# Migrations are applied automatically when the bot starts
dotnet run --project KfChatDotNetBot

Architecture Overview

Message Flow

KiwiFarms Chat (WebSocket)
          ↓
    ChatClient (WsClient library)
          ↓
    ChatBot (Event handlers)
          ↓
    BotCommands (Pattern matching)
          ↓
    ICommand implementations (Your commands)

Key Components

• ChatClient - WebSocket connection to KF, handles reconnection and cookie management
• ChatBot - Main bot orchestration, message tracking, GambaSesh detection
• BotCommands - Command routing with regex patterns, rate limiting, permissions
• BotServices - Manages all external service connections (Discord, Twitch, gambling sites)
• Money - Internal Kasino gambling system with balance tracking

Settings System

Settings are stored in the database, not config files:

• All settings have defaults defined in BuiltIn.cs
• Settings are cached to reduce database queries
• Secrets are marked and hidden from logs
• Settings sync automatically on startup

For more architectural details, see CLAUDE.md.

Logging

Logging is configured via NLog.config. The bot logs extensively:

• Debug: Packet details, message processing, connection events
• Info: User joins/parts, sent messages, state changes
• Error: Exceptions, disconnections, failed operations

Optional Services Setup

FlareSolverr (for Cloudflare bypass)

# Using Docker
docker run -d \
  --name=flaresolverr \
  -p 8191:8191 \
  ghcr.io/flaresolverr/flaresolverr:latest

# Update setting
UPDATE Settings SET Value = 'http://localhost:8191/' WHERE Key = 'FlareSolverr.ApiUrl';

Discord Bot

1. Create a bot at Discord Developer Portal
2. Get your bot token
3. Update setting: UPDATE Settings SET Value = 'your_bot_token' WHERE Key = 'Discord.Token';

Redis (for YouTube PubSub)

# Using Docker
docker run -d --name redis -p 6379:6379 redis:latest

# Update setting
UPDATE Settings SET Value = 'localhost:6379' WHERE Key = 'YouTube.PubSub.RedisConnectionString';

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See LICENSE for details.