mirror of
https://github.com/barelyprofessional/KfChatDotNet.git
synced 2026-05-02 04:22:04 -04:00
Nora (#87)
This commit is contained in:
xXCryingLaughingXx
committed by
GitHub
GitHub
parent
f701cae171
commit
30d9f48d2e
247
CLAUDE.md
Normal file
247
CLAUDE.md
Normal file
@@ -0,0 +1,247 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
KfChatDotNet is a C# .NET 10.0 chat bot for KiwiFarms (Sneedchat) with extensive third-party integrations. The solution consists of three projects:
|
||||
|
||||
- **KfChatDotNetWsClient**: WebSocket client library for KiwiFarms chat communication
|
||||
- **KickWsClient**: WebSocket client library for Kick platform integration
|
||||
- **KfChatDotNetBot**: Main bot application with command handling and service integrations
|
||||
|
||||
## Build and Development Commands
|
||||
|
||||
```bash
|
||||
# Build the entire solution
|
||||
dotnet build
|
||||
|
||||
# Build in Release mode
|
||||
dotnet build -c Release
|
||||
|
||||
# Run the bot
|
||||
dotnet run --project KfChatDotNetBot
|
||||
|
||||
# Clean build artifacts
|
||||
dotnet clean
|
||||
|
||||
# Restore NuGet packages
|
||||
dotnet restore
|
||||
```
|
||||
|
||||
## Database Management
|
||||
|
||||
The bot uses Entity Framework Core with SQLite (`db.sqlite`).
|
||||
|
||||
```bash
|
||||
# Add a new migration (from solution root)
|
||||
dotnet ef migrations add <MigrationName> --project KfChatDotNetBot
|
||||
|
||||
# Update database to latest migration
|
||||
dotnet ef database update --project KfChatDotNetBot
|
||||
|
||||
# Remove the last migration
|
||||
dotnet ef migrations remove --project KfChatDotNetBot
|
||||
|
||||
# View migration SQL
|
||||
dotnet ef migrations script --project KfChatDotNetBot
|
||||
```
|
||||
|
||||
Migrations run automatically on startup via `Program.cs`.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Message Flow
|
||||
|
||||
1. **ChatClient** ([KfChatDotNetWsClient/ChatClient.cs](KfChatDotNetWsClient/ChatClient.cs)): WebSocket connection and event emission
|
||||
- Connects to KiwiFarms WebSocket endpoint
|
||||
- Parses incoming packets and emits typed events
|
||||
- Handles reconnection logic and cookie management
|
||||
|
||||
2. **ChatBot** ([KfChatDotNetBot/ChatBot.cs](KfChatDotNetBot/ChatBot.cs)): Core bot orchestration
|
||||
- Subscribes to ChatClient events
|
||||
- Manages sent message tracking and auto-deletion
|
||||
- Handles GambaSesh presence detection
|
||||
- Coordinates with BotServices for external integrations
|
||||
|
||||
3. **BotCommands** ([KfChatDotNetBot/Services/BotCommands.cs](KfChatDotNetBot/Services/BotCommands.cs)): Command routing
|
||||
- Uses reflection to discover all ICommand implementations
|
||||
- Matches incoming messages against command regex patterns
|
||||
- Enforces rate limits, permissions, and timeouts
|
||||
- Filters based on user rights and Kasino bans/exclusions
|
||||
|
||||
4. **ICommand Implementations** ([KfChatDotNetBot/Commands/](KfChatDotNetBot/Commands/)): Individual command handlers
|
||||
- Each command defines regex patterns for matching
|
||||
- Commands specify required user rights and rate limits
|
||||
- Commands can be marked with attributes (NoPrefixRequired, KasinoCommand, WagerCommand, AllowAdditionalMatches)
|
||||
|
||||
### Command System
|
||||
|
||||
All commands implement `ICommand` interface:
|
||||
- `Patterns`: List of regex patterns for command matching
|
||||
- `HelpText`: Help text shown to users (null to hide from help)
|
||||
- `RequiredRight`: Minimum user permission level
|
||||
- `Timeout`: Command execution timeout
|
||||
- `RateLimitOptions`: Rate limiting configuration
|
||||
- `RunCommand()`: Async method that executes the command
|
||||
|
||||
Command attributes:
|
||||
- `[NoPrefixRequired]`: Command matches without requiring `!` prefix
|
||||
- `[AllowAdditionalMatches]`: Continue processing after this command matches
|
||||
- `[KasinoCommand]`: Requires Kasino to be enabled, enforces bans
|
||||
- `[WagerCommand]`: Enforces self-exclusions for gambling addicts
|
||||
|
||||
### Settings System
|
||||
|
||||
Settings are stored in the database (not config files) via `SettingsProvider`:
|
||||
- `SettingsProvider.GetValueAsync(key)` - Get a single setting
|
||||
- `SettingsProvider.GetMultipleValuesAsync(keys)` - Get multiple settings efficiently
|
||||
- `SettingsProvider.SetValueAsync(key, value)` - Update a setting
|
||||
- Built-in keys defined in `BuiltIn.Keys` static class
|
||||
- Migration from legacy `config.json` happens automatically on startup
|
||||
|
||||
### Service Integrations
|
||||
|
||||
**BotServices** ([KfChatDotNetBot/Services/BotServices.cs](KfChatDotNetBot/Services/BotServices.cs)) initializes and manages connections to external services:
|
||||
- Discord: Message relaying and bot presence
|
||||
- Twitch: Stream status monitoring and GraphQL API
|
||||
- Kick: WebSocket connection for stream events
|
||||
- Gambling sites: Rainbet, Shuffle, Howlgg, Chipsgg, Clashgg, BetBolt, Yeet
|
||||
- Stream platforms: DLive, PeerTube, Owncast, YouTube
|
||||
- Kasino: Internal gambling system with rain, mines, limbo, coinflip
|
||||
|
||||
Each service is implemented as a separate class in [KfChatDotNetBot/Services/](KfChatDotNetBot/Services/).
|
||||
|
||||
### Message Tracking
|
||||
|
||||
`ChatBot.SendChatMessage()` and `ChatBot.SendChatMessageAsync()` return a `SentMessageTrackerModel`:
|
||||
- Tracks message status (WaitingForResponse, ResponseReceived, Lost, NotSending)
|
||||
- Provides message ID for editing/deletion
|
||||
- Measures round-trip delay
|
||||
- Supports auto-deletion after a specified TimeSpan
|
||||
- Handles message replay after disconnection
|
||||
|
||||
### Database Schema
|
||||
|
||||
The `ApplicationDbContext` manages these entities:
|
||||
- `Users`: KiwiFarms users with permissions
|
||||
- `Gamblers`: Kasino users with balance and stats
|
||||
- `Transactions`: Kasino transaction history
|
||||
- `Wagers`: Active and historical bets
|
||||
- `Exclusions`: Self-exclusion periods
|
||||
- `Perks`: Gambler perks (e.g., reduced house edge)
|
||||
- `Settings`: Bot configuration
|
||||
- `Images`: Uploaded image metadata
|
||||
- `UsersWhoWere`: User activity timestamps (join/part/message)
|
||||
- Various third-party service data tables (HowlggBets, RainbetBets, etc.)
|
||||
|
||||
## Important Patterns
|
||||
|
||||
### Async/Await Conventions
|
||||
|
||||
The codebase has inconsistent async patterns:
|
||||
- Some methods expose both sync and async versions (e.g., `SendChatMessage()` and `SendChatMessageAsync()`)
|
||||
- `Disconnect()` is intentionally synchronous with a separate `DisconnectAsync()` method
|
||||
- Avoid changing existing sync/async signatures without careful consideration
|
||||
|
||||
### GambaSesh Detection
|
||||
|
||||
GambaSesh is another bot that the bot avoids conflicting with:
|
||||
- `ChatBot.GambaSeshPresent` tracks his presence
|
||||
- Messages are suppressed by default when he's present (unless `bypassSeshDetect=true`)
|
||||
- Presence is detected via user join events and messages
|
||||
- `BotServices.TemporarilyBypassGambaSeshForDiscord` exists for special cases
|
||||
|
||||
### Length Limits
|
||||
|
||||
Sneedchat enforces a 1023-byte message limit:
|
||||
- `SendChatMessage()` accepts `LengthLimitBehavior` enum: TruncateNicely, TruncateExactly, RefuseToSend, DoNothing
|
||||
- Use `string.Utf8LengthBytes()` extension method to check length
|
||||
- Use `string.TruncateBytes(limit)` extension method to truncate safely
|
||||
|
||||
### Session Management
|
||||
|
||||
The bot handles KiwiFarms authentication via cookies:
|
||||
- `KfTokenService` manages login and cookie refresh
|
||||
- On `203` status code or "cannot join room" errors, cookies are refreshed
|
||||
- Cookies are persisted to the database
|
||||
- Bot can operate in "guest mode" with no cookies
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding a New Command
|
||||
|
||||
1. Create a new class in `KfChatDotNetBot/Commands/` that implements `ICommand`
|
||||
2. Define regex patterns in the `Patterns` property
|
||||
3. Implement `RunCommand()` method with command logic
|
||||
4. Set `RequiredRight`, `Timeout`, `RateLimitOptions`, and `HelpText`
|
||||
5. Add attributes if needed: `[NoPrefixRequired]`, `[KasinoCommand]`, etc.
|
||||
6. The command will be auto-discovered via reflection on next startup
|
||||
|
||||
### Adding a New Service Integration
|
||||
|
||||
1. Create a new class in `KfChatDotNetBot/Services/`
|
||||
2. Add initialization method to `BotServices.InitializeServices()`
|
||||
3. Add corresponding settings keys to `BuiltIn.Keys`
|
||||
4. If the service needs WebSocket or periodic tasks, follow existing patterns (PeriodicTimer, WebsocketClient)
|
||||
|
||||
### Modifying the Database Schema
|
||||
|
||||
1. Update the relevant `DbModel` class in `KfChatDotNetBot/Models/DbModels/`
|
||||
2. Add/update the `DbSet` property in `ApplicationDbContext.cs`
|
||||
3. Generate a migration: `dotnet ef migrations add <Name> --project KfChatDotNetBot`
|
||||
4. Migration runs automatically on next bot startup
|
||||
|
||||
### Sending Messages to Chat
|
||||
|
||||
```csharp
|
||||
// Synchronous
|
||||
var tracker = _bot.SendChatMessage("Hello!");
|
||||
|
||||
// Asynchronous
|
||||
var tracker = await _bot.SendChatMessageAsync("Hello!");
|
||||
|
||||
// Bypass GambaSesh detection
|
||||
_bot.SendChatMessage("Important message", bypassSeshDetect: true);
|
||||
|
||||
// Auto-delete after 5 seconds
|
||||
await _bot.SendChatMessageAsync("Temporary message", autoDeleteAfter: TimeSpan.FromSeconds(5));
|
||||
|
||||
// Wait for the message to be echoed by the server
|
||||
if (await _bot.WaitForChatMessageAsync(tracker, TimeSpan.FromSeconds(10)))
|
||||
{
|
||||
// Message was successfully sent, tracker.ChatMessageId is now available
|
||||
}
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
Key NuGet packages:
|
||||
- `Websocket.Client`: WebSocket client used throughout
|
||||
- `Microsoft.EntityFrameworkCore.Sqlite`: Database ORM
|
||||
- `NLog`: Logging framework
|
||||
- `Humanizer.Core`: Human-readable text formatting
|
||||
- `SixLabors.ImageSharp`: Image manipulation for meme generation
|
||||
- `StackExchange.Redis`: Redis caching
|
||||
- `FlareSolverrSharp`: Cloudflare bypass
|
||||
- `HtmlAgilityPack`: HTML parsing
|
||||
- `Nerdbank.GitVersioning`: Automatic versioning from git tags
|
||||
|
||||
## Testing
|
||||
|
||||
There are currently no automated tests in this repository. Manual testing is performed by running the bot.
|
||||
|
||||
## Logging
|
||||
|
||||
NLog configuration is in `KfChatDotNetBot/NLog.config`. The bot logs extensively:
|
||||
- Debug: Detailed packet information, message processing steps
|
||||
- Info: User joins/parts, sent messages, state changes
|
||||
- Error: Exceptions, disconnections, failed operations
|
||||
|
||||
## Code Style Notes
|
||||
|
||||
- The codebase uses explicit null checks and nullable reference types
|
||||
- Extensive use of LINQ for data queries
|
||||
- Some deliberately provocative comments and language (see Program.cs license header)
|
||||
- Privacy is explicitly not a concern - data is logged freely
|
||||
- Performance optimizations include "BUY MORE RAM" philosophy (unlimited message tracking)
|
||||
Reference in New Issue
Block a user