Merge pull request #5 from musarrat950/debugbranch

Fixing major and critical bugs, adding more support to the plug-in system, and improving a lot of ways to introduce a much more centralized way of developing plugins

Author: Coder-soft

.env.example

@@ -1,4 +1,4 @@
-# Holo Bridge - Environment Variables
+# HoloBridge - Environment Configuration
 
 # Discord Bot Token (required)
 # Get this from https://discord.com/developers/applications
@@ -8,5 +8,18 @@ DISCORD_TOKEN=your_discord_bot_token_here
 PORT=3000
 API_KEY=your_secure_api_key_here
 
-# Optional: Enable debug logging
+# Optional: Multiple API keys with scopes (JSON array)
+# API_KEYS=[{"id":"key1","name":"Read Only","key":"readonly_key","scopes":["read:guilds","read:messages"]}]
+
+# Plugin System
+PLUGINS_ENABLED=true
+PLUGINS_DIR=plugins
+
+# Rate Limiting
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_WINDOW_MS=60000
+RATE_LIMIT_MAX=100
+
+# Debug Mode
 DEBUG=false
+

Dockerfile

@@ -0,0 +1,44 @@
+# Stage 1: Build
+FROM node:18-alpine AS builder
+
+WORKDIR /app
+
+# Copy package files
+COPY package*.json ./
+
+# Install all dependencies (including dev for building)
+RUN npm ci
+
+# Copy source code
+COPY . .
+
+# Build TypeScript
+RUN npm run build
+
+# Stage 2: Production
+FROM node:18-alpine
+
+WORKDIR /app
+
+# Copy built files from builder
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/package*.json ./
+
+# Install production dependencies only
+RUN npm ci --production
+
+# Create plugins directory
+RUN mkdir -p plugins
+
+# Install wget for healthcheck
+RUN apk add --no-cache wget
+
+# Expose API port
+EXPOSE 3000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1
+
+# Run the application
+CMD ["npm", "start"]

README.md

@@ -1,46 +1,127 @@
-# Holo Bridge
+# HoloBridge
 
-A type-safe TypeScript bridge between websites and Discord bots. Provides a REST API and WebSocket interface for full Discord bot capabilities.
+A type-safe TypeScript bridge between websites and Discord bots. Provides a REST API, WebSocket interface, and plugin system for full Discord bot capabilities.
 
 ## Features
 
 - **REST API** for all Discord operations
 - **WebSocket** real-time event streaming
+- **Plugin System** for extensibility
+- **Granular API Scopes** for secure access control
+- **Rate Limiting** for API protection
+- **CLI Tool** for easy management
+- **Docker Ready** for easy deployment
 - **Type-safe** with Zod validation
-- **Full Discord.js coverage**:
-  - Guilds, Channels, Roles
-  - Members, Bans, Timeouts
-  - Messages, Reactions, Pins
-  - Voice state tracking
-  - And more...
 
 ## Quick Start
 
-### 1. Install Dependencies
+### Option 1: Using the CLI
 
 ```bash
+# Install globally
+npm install -g holobridge
+
+# Initialize configuration
+holo init
+
+# Check your setup
+holo doctor
+
+# Start the server
+holo start
+```
+
+### Option 2: Manual Setup
+
+```bash
+# Install dependencies
 npm install
+
+# Copy environment file
+cp .env.example .env
+# Edit .env with your Discord token and API key
+
+# Build and run
+npm run build
+npm start
+```
+
+### Option 3: Docker
+
+```bash
+# Using Docker Compose
+docker-compose up -d
+
+# Or build manually
+docker build -t holobridge .
+docker run -p 3000:3000 --env-file .env holobridge
 ```
 
-### 2. Configure Environment
+## Configuration
 
-Copy `.env.example` to `.env` and fill in your values:
+Copy `.env.example` to `.env` and configure:
 
 ```env
+# Required
 DISCORD_TOKEN=your_discord_bot_token
 API_KEY=your_secure_api_key
+
+# Optional
 PORT=3000
+DEBUG=false
+PLUGINS_ENABLED=true
+RATE_LIMIT_ENABLED=true
+RATE_LIMIT_MAX=100
 ```
 
-### 3. Run
+### Multiple API Keys with Scopes
 
-```bash
-# Development
-npm run dev
+For granular access control, use the `API_KEYS` environment variable:
 
-# Production
-npm run build
-npm start
+```env
+API_KEYS=[{"id":"readonly","name":"Dashboard","key":"dash_xxx","scopes":["read:guilds","read:messages"]}]
+```
+
+**Available Scopes:**
+- `read:guilds`, `read:channels`, `read:members`, `read:messages`
+- `write:messages`, `write:members`, `write:channels`, `write:roles`
+- `events` (WebSocket access)
+- `admin` (full access)
+
+## Plugin System
+
+Extend HoloBridge with custom plugins. Create `.js` files in the `plugins/` directory:
+
+```javascript
+export default {
+    metadata: {
+        name: 'my-plugin',
+        version: '1.0.0',
+    },
+
+    onLoad(ctx) {
+        ctx.log('Plugin loaded!');
+        // ctx.client - Discord.js Client
+        // ctx.io - Socket.IO Server
+    },
+
+    onEvent(eventName, data) {
+        if (eventName === 'messageCreate') {
+            // React to messages
+        }
+    },
+};
+```
+
+See [plugins/README.md](plugins/README.md) for full documentation.
+
+## CLI Commands
+
+```bash
+holo start          # Start the server
+holo start --watch  # Development mode with hot reload
+holo doctor         # Check configuration and environment
+holo init           # Interactive setup wizard
 ```
 
 ## API Reference
@@ -53,6 +134,13 @@ All API requests require the `X-API-Key` header:
 curl -H "X-API-Key: your_key" http://localhost:3000/api/guilds
 ```
 
+### Rate Limiting
+
+Responses include rate limit headers:
+- `X-RateLimit-Limit` - Max requests per window
+- `X-RateLimit-Remaining` - Requests remaining
+- `X-RateLimit-Reset` - Unix timestamp when limit resets
+
 ### REST Endpoints
 
 | Method | Endpoint | Description |
@@ -68,6 +156,7 @@ curl -H "X-API-Key: your_key" http://localhost:3000/api/guilds
 | `POST` | `/api/channels/:id/messages` | Send message |
 | `PATCH` | `/api/channels/:id/messages/:msgId` | Edit message |
 | `DELETE` | `/api/channels/:id/messages/:msgId` | Delete message |
+| `GET` | `/health` | Health check (no auth) |
 
 ### WebSocket Events
 
@@ -80,33 +169,48 @@ const socket = io('http://localhost:3000', {
   auth: { apiKey: 'your_key' }
 });
 
-// Subscribe to guild events
 socket.emit('subscribe', { guildIds: ['123456789'] });
 
-// Listen for Discord events
 socket.on('discord', (event) => {
   console.log(event.event, event.data);
 });
 ```
 
-**Events:** `messageCreate`, `messageUpdate`, `messageDelete`, `guildMemberAdd`, `guildMemberRemove`, `voiceStateUpdate`, and more.
+**Supported Events (45+):** Messages, Reactions, Members, Channels, Threads, Roles, Guilds, Emojis, Voice, Scheduled Events, AutoMod, Invites, Interactions, and more.
 
 ## Discord Bot Setup
 
 1. Go to [Discord Developer Portal](https://discord.com/developers/applications)
-2. Create a new application
-3. Go to Bot section and create a bot
-4. Enable these **Privileged Gateway Intents**:
+2. Create a new application and bot
+3. Enable **ALL Privileged Gateway Intents**:
    - Presence Intent
    - Server Members Intent
    - Message Content Intent
-5. Copy the token to your `.env` file
-6. Invite the bot to your server with appropriate permissions
+4. Copy the token to your `.env` file
+5. Invite the bot with `Administrator` permissions
 
-## Documentation
+## Project Structure
 
-Visit the [documentation](https://holodocs.pages.dev/) for more details.
+```
+holobridge/
+├── bin/holo.js          # CLI tool
+├── plugins/             # Plugin directory
+├── src/
+│   ├── api/             # REST API routes & middleware
+│   ├── discord/         # Discord client & events
+│   ├── plugins/         # Plugin manager
+│   └── types/           # TypeScript types
+├── Dockerfile           # Docker build
+└── docker-compose.yml   # Docker Compose config
+```
+
+## Resources
+
+- [Use Cases](USE_CASES.md) - Creative ways to use HoloBridge
+- [Plugin Guide](plugins/README.md) - How to build plugins
+- [Documentation](https://holodocs.pages.dev/) - Full API docs
 
 ## License
 
 MIT
+