📚 Documentation - Auto Kick Bot

Table of Contents

1. General Overview
2. Discord Developer Configuration
3. Project Setup
4. Complete Setup Guide
5. Available Commands
6. Project Structure
7. config.ts Configuration

---

General Overview

Auto Kick Bot is a Discord bot developed with Discord.js and TypeScript that detects inactive members (those who haven't sent messages) on a server and facilitates their management.

Main Features

• ✅ Detects inactive members on the server
• ✅ Saves member data in JSON files
• ✅ Verifies moderation permissions
• ✅ Real-time message monitoring
• ✅ Scalable system based on Clean Architecture

---

Discord Developer Configuration

Step 1: Create an Application in Discord Developer Portal

1. Access Discord Developer Portal: https://discord.com/developers/applications
2. Click "New Application"
3. Assign a name to the bot (e.g., "Auto Kick Bot")
4. Accept the terms and create the application

Step 2: Get the Bot Token

1. Go to the "Bot" section in the left menu
2. Click "Add Bot"
3. Under the TOKEN section, click "Copy"
4. Save this token securely (it's like a password)

⚠️ IMPORTANT: Never share your token publicly. If exposed, regenerate it immediately.

Step 3: Get the Application ID

1. In the "General Information" section
2. Copy the CLIENT ID (this is your APP_ID)

Step 4: Configure Bot Permissions

1. Go to "OAuth2" → "URL Generator"
2. In Scopes, select:
   • ✅ bot
3. In Permissions, select:
   • ✅ Read Messages/View Channels
   • ✅ Send Messages
   • ✅ Read Message History
   • ✅ Kick Members (to kick members)
   • ✅ Manage Messages
4. Copy the generated URL and open it in your browser
5. Select the server where you want to add the bot

Step 5: Get the Channel ID

1. Open Discord and go to your server
2. Enable "Developer Mode":
   • Windows: Ctrl+Shift+I → User Settings → Advanced → Developer Mode
   • Mac: Cmd+Shift+I → User Settings → Advanced → Developer Mode
3. Right-click on the channel you want to monitor
4. Select "Copy Channel ID"

---

Project Setup

Prerequisites

• Node.js (v16 or higher): https://nodejs.org
• npm (included with Node.js)
• Git (optional, to clone the repository)
• Discord Developer credentials

Installation Steps

1. Clone or download the project

git clone <repository-url>
cd auto-kick-bot

2. Install dependencies

npm install

This will install:

• discord.js - Library to interact with Discord
• dotenv - Environment variables management
• typescript - Typed language
• ts-node - TypeScript executor in development
• nodemon - Automatic change monitor

3. Create .env file

In the project root, create a file named .env with the following content:

DISCORD_TOKEN=your_token_here
APP_ID=your_app_id_here
ID_CHANNEL=your_channel_id_here

Complete example:

DISCORD_TOKEN=dsaddsadas.dsadasdas.dasjda90121j00ssjsd0as
APP_ID=1283091iodsaoidj10
ID_CHANNEL=0912oindsondosa

⚠️ IMPORTANT:

• Never commit the .env file to Git
• Verify that .gitignore includes .env
• Keep your credentials secure

---

Complete Setup Guide

Option A: Development Mode (Recommended for testing)

# 1. Install dependencies
npm install

# 2. Create .env file with your credentials

# 3. Run in development mode with hot-reload
npm run dev

The bot will automatically restart when you make code changes.

Expected output:

✅ Bot is ready! What are we gonna do?

Option B: Production Mode

# 1. Compile TypeScript to JavaScript
npm run build

# 2. Run the compiled bot
npm start

This will generate compiled files in the dist/ folder.

---

Available Commands

1️⃣ !hello

Description: Verifies that the bot is active Usage: Type !hello in any channel Response: ESTOY ACTIVO PUTO IMBECIL ✅

User: !hello
Bot: ESTOY ACTIVO PUTO IMBECIL ✅

2️⃣ !check

Description: Scans all server members and detects inactive ones Usage: Type !check in a configured channel Requirements:

• The bot needs message read permissions
• A JSON file will be saved with the data

Result: Creates file data/members-<timestamp>.json with inactive members

Generated JSON structure:

{
  "id": "user_id_discord",
  "username": "username",
  "joinedAt": "2024-01-15T10:30:00.000Z",
  "messageCount": 0
}

3️⃣ !checkme

Description: Checks if you have moderation permissions Usage: Type !checkme Responses:

• ✅ If you have permissions: ✅ Tienes el permiso 'KICK_MEMBERS'.
• ❌ If you don't have permissions: ❌ No tienes el permiso 'KICK_MEMBERS'.

User (with permissions): !checkme
Bot: ✅ Tienes el permiso `KICK_MEMBERS`.

User (without permissions): !checkme
Bot: ❌ No tienes el permiso `KICK_MEMBERS`.

---

Project Structure

auto-kick-bot/
├── src/
│   ├── config/
│   │   └── config.ts              # Central configuration
│   ├── domain/
│   │   ├── models/
│   │   │   ├── user.models.ts     # User interface
│   │   │   └── stats.model.ts     # Statistics interface
│   │   └── repository/
│   │       └── member.repository.ts # Repository interface
│   ├── application/
│   │   └── use-cases/
│   │       └── inactive-members.use-case.ts # Inactive members logic
│   ├── infrastructure/
│   │   └── discord/
│   │       └── discord-member.repository.ts # Discord implementation
│   ├── adapters/
│   │   └── save-members-command.adapter.ts  # Command adapter
│   ├── utils/
│   │   └── channels.ts            # Channel utilities
│   └── main.ts                    # Bot entry point
├── data/                          # Generated JSON files
├── dist/                          # Compiled files (production)
├── .env                           # Environment variables (DO NOT commit)
├── .gitignore                     # Ignore files
├── package.json                   # Dependencies and scripts
├── tsconfig.json                  # TypeScript configuration
└── DOCUMENTATION.md               # This documentation

Architecture Pattern: Clean Architecture

The project implements Clean Architecture to separate responsibilities:

• Domain: Models and interfaces (no external dependencies)
• Application: Use cases (business logic)
• Infrastructure: Implementation with Discord
• Adapters: Layer connectors
• Config: Centralized configuration

---

config.ts Configuration

📄 Complete File

import dotenv from "dotenv"

dotenv.config();

export const config = {
    token: process.env.DISCORD_TOKEN,
    appId: process.env.APP_ID,
    channelId: process.env.ID_CHANNEL,
    messageLength: 0,
    days: null,
}

📋 Detailed Explanation of Each Property

1. token: process.env.DISCORD_TOKEN

• Type: string
• Source: Environment variable DISCORD_TOKEN
• Description: Bot authentication token on Discord
• Usage: Used in main.ts with client.login(config.token)
• Example:

  dsaddsadas.dsadasdas.dasjda90121j00ssjsd0as
  

• ⚠️ Critical: Never expose it publicly

2. appId: process.env.APP_ID

• Type: string
• Source: Environment variable APP_ID
• Description: Unique application ID on Discord (Client ID)
• Usage: To identify the application on Discord
• Example:

  12131312s12312dsa122123
  

• Where to find it: Discord Developer Portal → General Information → CLIENT ID

3. channelId: process.env.ID_CHANNEL ⚠️ NOTE: NOT BEING USED

• Type: string
• Source: Environment variable ID_CHANNEL
• Status: Deprecated - Not used in the current application
• Description: ID of the Discord channel where members are monitored
• ⚠️ Important: This value in config.ts DOES NOT WORK.

Instead, use the file src/utils/channels.ts:

// src/utils/channels.ts
export const CHANNELS_IDS = [
    "3213123214sas123213213",
]

To add more channels, simply add IDs to the array:

export const CHANNELS_IDS = [
    "3123213123213213",
    "3213123213213213213",
    "12312321321321312",
]

• How to get channel IDs:
  1. Enable Developer Mode in Discord (Ctrl+Shift+I)
  2. Right-click on the channel → Copy Channel ID
  3. Add the ID to the array in src/utils/channels.ts

4. messageLength: 0

• Type: number
• Current value: 0
• Description: Maximum message threshold to consider a user as inactive
• Usage: In inactive-members.use-case.ts to filter inactive users
• Logic:

  // If messageLength = 0:
  const inactive = data.users.filter(user => user.messageCount === 0);
  // Filters only users with 0 messages

• Configuration examples:
  • 0 → Inactive = users with 0 messages
  • 5 → Inactive = users with 0-5 messages
  • 10 → Inactive = users with 0-10 messages

5. days: null

• Type: null (currently unused)
• Current value: null
• Description: Number of inactivity days (future feature)
• Usage: Reserved to filter by inactivity time
• Future implementation:

  // Pseudo-code for future use:
  if (config.days) {
      const dayLimit = Date.now() - (config.days * 24 * 60 * 60 * 1000);
      const inactive = users.filter(u => u.lastMessageDate < dayLimit);
  }

---

Environment Variables Summary (.env)

Variable	Description	Example	Where to get it
DISCORD_TOKEN	Bot token	MTMz...	Developer Portal → Bot → TOKEN
APP_ID	Client ID	312312321312312312	Developer Portal → General Information
ID_CHANNEL	Channel ID	312321321321321312	Right-click on channel → Copy ID

---

Troubleshooting

❌ Error: "TOKEN is undefined"

Cause: The .env file doesn't exist or doesn't have the DISCORD_TOKEN variable Solution:

1. Create the .env file in the root
2. Add: DISCORD_TOKEN=your_token_here

❌ Error: "Bot cannot login"

Cause: Invalid or expired token Solution:

1. Regenerate the token in Developer Portal
2. Update the .env file

❌ Bot doesn't respond to commands

Cause:

• The bot doesn't have permissions on the server
• The channel isn't configured correctly Solution:

1. Check permissions in Discord → Server → Bot Roles
2. Run !checkme to verify permissions
3. Check that CHANNELS_IDS in src/utils/channels.ts is correct

❌ Error: "Cannot find module discord.js"

Cause: Dependencies not installed Solution:

npm install

---

Available Scripts

npm run dev

Starts the bot in development mode with automatic restart

npm run dev

npm run build

Compiles TypeScript to JavaScript

npm run build
# Generates files in the 'dist/' folder

npm start

Runs the compiled bot (production)

npm start

npm test

Runs tests (currently not configured)

npm test

---

Next Steps / Future Improvements

1. ✅ Implement filtering logic by days (config.days)
2. ✅ Add !kick command to remove inactive users
3. ✅ Implement persistent database
4. ✅ Add more granular roles and permissions
5. ✅ Web dashboard to visualize data
6. ✅ Per-server configuration

---

Contact and Support

For bug reports or suggestions, contact the project developer.

---

Last updated: January 2026
Version: 1.0.0
License: ISC