From b1d058dd4917474a3b1e0032cdd92e8dfee93a71 Mon Sep 17 00:00:00 2001 From: Coder-soft Date: Sat, 6 Dec 2025 16:27:13 +0500 Subject: [PATCH 01/11] docs: Add initial documentation pages and styling for the Discord Web Bridge. --- docs/getting-started.html | 190 +++++++++++++++ docs/index.html | 130 ++++++++++ docs/styles.css | 498 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 818 insertions(+) create mode 100644 docs/getting-started.html create mode 100644 docs/index.html create mode 100644 docs/styles.css diff --git a/docs/getting-started.html b/docs/getting-started.html new file mode 100644 index 0000000..8eef0c6 --- /dev/null +++ b/docs/getting-started.html @@ -0,0 +1,190 @@ + + + + + + + Getting Started - Discord Web Bridge + + + + + +
+
+ + +
+
+ +
+
+

Getting Started

+

This guide will walk you through installing, configuring, and running Discord Web Bridge.

+ +

Prerequisites

+
    +
  • Node.js 18 or higher
    • +
  • npm or yarn package manager
    • +
  • A Discord bot token
    • +
+ +

Installation

+

1. Clone the Repository

+ 
git clone https://github.com/your-repo/discord-web-bridge.git
+cd discord-web-bridge
+ +

2. Install Dependencies

+ 
npm install
+ +

Configuration

+

Environment Variables

+

Copy .env.example to .env and fill in your values:

+ 
# Discord Bot Token (required)
+# Get this from https://discord.com/developers/applications
+DISCORD_TOKEN=your_discord_bot_token_here
+
+# API Configuration
+PORT=3000
+API_KEY=your_secure_api_key_here
+
+# Optional: Enable debug logging
+DEBUG=false
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableRequiredDescription
DISCORD_TOKENYesYour Discord bot token
API_KEYYesAPI key for authenticating requests
PORTNoServer port (default: 3000)
DEBUGNoEnable debug logging (default: false)
+ +

Running the Server

+

Development Mode

+ 
npm run dev
+ +

Production Mode

+ 
npm run build
+npm start
+ +

Discord Bot Setup

+

Follow these steps to create a Discord bot and invite it to your server:

+ +
    +
  1. Go to the Discord Developer + Portal
    2. +
  2. Click "New Application" and give it a name
    3. +
  3. Go to the "Bot" section in the left sidebar
    4. +
  4. Click "Add Bot" and confirm
    5. +
  5. Enable the following Privileged Gateway Intents: +
      +
    • Presence Intent
      • +
    • Server Members Intent
      • +
    • Message Content Intent
      • +
    +
    6. +
  6. Click "Reset Token" to get your bot token and copy it to your .env file
    7. +
+ +

Inviting the Bot

+
    +
  1. Go to the "OAuth2" → "URL Generator" section
    2. +
  2. Select the following scopes: +
      +
    • bot
      • +
    • applications.commands
      • +
    +
    3. +
  3. Select the permissions your bot needs (Administrator for full access)
    4. +
  4. Copy the generated URL and open it in your browser
    5. +
  5. Select a server and authorize the bot
    6. +
+ +
+ ⚠️ Important: Keep your bot token and API key secret. Never commit them to version + control. +
+ +

Testing the API

+

Once the server is running, you can test the API with curl:

+ 
# List all guilds
+curl -H "X-API-Key: your_api_key" http://localhost:3000/api/guilds
+ +

Next Steps

+
+ +

📖 API Reference

+

Explore all available REST API endpoints.

+ + +

⚡ WebSocket Events

+

Learn how to receive real-time Discord events.

+ +
+
+
+ + + + + + + \ No newline at end of file diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..03fc2dd --- /dev/null +++ b/docs/index.html @@ -0,0 +1,130 @@ + + + + + + Discord Web Bridge - Documentation + + + + +
+
+ + +
+
+ +
+
+
+

Discord Web Bridge

+

A type-safe TypeScript bridge between websites and Discord bots. Provides a REST API and WebSocket interface for full Discord bot capabilities.

+
+ Get Started + API Reference +
+
+ +
+
+

🌐 REST API

+

Full REST API for all Discord operations including guilds, channels, messages, members, and roles.

+
+
+

⚡ WebSocket Events

+

Real-time event streaming via Socket.IO. Subscribe to guilds and receive Discord events instantly.

+
+
+

🔒 Type-Safe

+

Built with TypeScript and Zod validation. Every request and response is fully typed.

+
+
+

📦 Full Coverage

+

Guilds, Channels, Roles, Members, Bans, Timeouts, Messages, Reactions, Pins, and more.

+
+
+ +

Quick Links

+
+ +

📚 Getting Started

+

Installation, configuration, and running the server.

+ + +

📖 API Reference

+

Complete REST API endpoint documentation.

+ + +

⚡ WebSocket Events

+

Real-time event streaming documentation.

+ + +

💻 Source Code

+

View the source code on GitHub.

+ +
+ +

Features Overview

+

Discord Operations

+
    +
  • Guilds - List guilds, get details, channels, roles, emojis, bans, invites
    • +
  • Channels - Create, edit, delete channels and threads
    • +
  • Messages - Send, edit, delete, bulk delete, reactions, pins
    • +
  • Members - List, search, kick, ban, timeout, role management
    • +
  • Roles - Create, edit, delete, permissions management
    • +
+ +

Real-Time Events

+
    +
  • Message Events - messageCreate, messageUpdate, messageDelete
    • +
  • Member Events - guildMemberAdd, guildMemberRemove, guildMemberUpdate
    • +
  • Channel Events - channelCreate, channelUpdate, channelDelete
    • +
  • Role Events - roleCreate, roleUpdate, roleDelete
    • +
  • Voice Events - voiceStateUpdate
    • +
  • Guild Events - guildBanAdd, guildBanRemove
    • +
+
+
+ + + + + + diff --git a/docs/styles.css b/docs/styles.css new file mode 100644 index 0000000..89d608d --- /dev/null +++ b/docs/styles.css @@ -0,0 +1,498 @@ +/* Discord Web Bridge - Documentation Styles */ +/* Simple design with dark/light theme support */ + +:root { + /* Light theme (default) */ + --bg-primary: #ffffff; + --bg-secondary: #f5f5f5; + --bg-tertiary: #e8e8e8; + --text-primary: #1a1a1a; + --text-secondary: #555555; + --text-muted: #888888; + --border-color: #dddddd; + --accent: #5865f2; + --accent-hover: #4752c4; + --success: #3ba55c; + --warning: #faa61a; + --error: #ed4245; + --code-bg: #f0f0f0; + --table-stripe: #fafafa; +} + +[data-theme="dark"] { + --bg-primary: #1a1a1a; + --bg-secondary: #252525; + --bg-tertiary: #333333; + --text-primary: #ffffff; + --text-secondary: #b0b0b0; + --text-muted: #777777; + --border-color: #444444; + --accent: #5865f2; + --accent-hover: #7289da; + --success: #3ba55c; + --warning: #faa61a; + --error: #ed4245; + --code-bg: #2d2d2d; + --table-stripe: #222222; +} + +@media (prefers-color-scheme: dark) { + :root:not([data-theme="light"]) { + --bg-primary: #1a1a1a; + --bg-secondary: #252525; + --bg-tertiary: #333333; + --text-primary: #ffffff; + --text-secondary: #b0b0b0; + --text-muted: #777777; + --border-color: #444444; + --accent: #5865f2; + --accent-hover: #7289da; + --success: #3ba55c; + --warning: #faa61a; + --error: #ed4245; + --code-bg: #2d2d2d; + --table-stripe: #222222; + } +} + +/* Reset and base styles */ +*, *::before, *::after { + box-sizing: border-box; + margin: 0; + padding: 0; +} + +html { + scroll-behavior: smooth; +} + +body { + font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif; + background-color: var(--bg-primary); + color: var(--text-primary); + line-height: 1.6; + min-height: 100vh; +} + +/* Layout */ +.container { + max-width: 1200px; + margin: 0 auto; + padding: 0 24px; +} + +/* Header */ +header { + background-color: var(--bg-secondary); + border-bottom: 1px solid var(--border-color); + padding: 16px 0; + position: sticky; + top: 0; + z-index: 100; +} + +.header-content { + display: flex; + justify-content: space-between; + align-items: center; +} + +.logo { + font-size: 1.5rem; + font-weight: 700; + color: var(--accent); + text-decoration: none; +} + +nav { + display: flex; + gap: 24px; + align-items: center; +} + +nav a { + color: var(--text-secondary); + text-decoration: none; + font-weight: 500; + transition: color 0.2s ease; +} + +nav a:hover, +nav a.active { + color: var(--accent); +} + +/* Theme toggle */ +.theme-toggle { + background-color: var(--bg-tertiary); + border: 1px solid var(--border-color); + border-radius: 12px; + padding: 8px 16px; + cursor: pointer; + color: var(--text-primary); + font-size: 0.875rem; + font-weight: 500; + transition: all 0.2s ease; +} + +.theme-toggle:hover { + background-color: var(--accent); + color: #ffffff; + border-color: var(--accent); +} + +/* Main content */ +main { + padding: 48px 0; +} + +/* Hero section */ +.hero { + text-align: center; + padding: 64px 0; +} + +.hero h1 { + font-size: 3rem; + font-weight: 800; + margin-bottom: 16px; + color: var(--text-primary); +} + +.hero p { + font-size: 1.25rem; + color: var(--text-secondary); + max-width: 600px; + margin: 0 auto 32px; +} + +/* Buttons - squircle style */ +.btn { + display: inline-block; + padding: 12px 24px; + border-radius: 12px; + text-decoration: none; + font-weight: 600; + font-size: 1rem; + cursor: pointer; + transition: all 0.2s ease; + border: none; +} + +.btn-primary { + background-color: var(--accent); + color: #ffffff; +} + +.btn-primary:hover { + background-color: var(--accent-hover); +} + +.btn-secondary { + background-color: var(--bg-tertiary); + color: var(--text-primary); + border: 1px solid var(--border-color); +} + +.btn-secondary:hover { + background-color: var(--bg-secondary); + border-color: var(--accent); +} + +.btn-group { + display: flex; + gap: 16px; + justify-content: center; + flex-wrap: wrap; +} + +/* Features grid */ +.features { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); + gap: 24px; + padding: 48px 0; +} + +.feature-card { + background-color: var(--bg-secondary); + border: 1px solid var(--border-color); + border-radius: 12px; + padding: 24px; +} + +.feature-card h3 { + font-size: 1.25rem; + margin-bottom: 12px; + color: var(--text-primary); +} + +.feature-card p { + color: var(--text-secondary); +} + +/* Section headings */ +h1, h2, h3, h4, h5, h6 { + color: var(--text-primary); + line-height: 1.3; +} + +h1 { font-size: 2.5rem; margin-bottom: 24px; } +h2 { font-size: 2rem; margin: 48px 0 24px; } +h3 { font-size: 1.5rem; margin: 32px 0 16px; } +h4 { font-size: 1.25rem; margin: 24px 0 12px; } + +/* Prose content */ +p { + margin-bottom: 16px; + color: var(--text-secondary); +} + +a { + color: var(--accent); + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +ul, ol { + margin: 16px 0; + padding-left: 24px; + color: var(--text-secondary); +} + +li { + margin-bottom: 8px; +} + +/* Code blocks */ +code { + font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace; + background-color: var(--code-bg); + padding: 2px 6px; + border-radius: 4px; + font-size: 0.9em; +} + +pre { + background-color: var(--code-bg); + border: 1px solid var(--border-color); + border-radius: 12px; + padding: 16px; + overflow-x: auto; + margin: 16px 0; +} + +pre code { + background: none; + padding: 0; +} + +/* Tables */ +table { + width: 100%; + border-collapse: collapse; + margin: 24px 0; + font-size: 0.95rem; +} + +th, td { + text-align: left; + padding: 12px 16px; + border-bottom: 1px solid var(--border-color); +} + +th { + background-color: var(--bg-secondary); + font-weight: 600; + color: var(--text-primary); +} + +tbody tr:nth-child(even) { + background-color: var(--table-stripe); +} + +/* Method badges */ +.method { + display: inline-block; + padding: 4px 8px; + border-radius: 6px; + font-size: 0.75rem; + font-weight: 700; + font-family: monospace; + text-transform: uppercase; +} + +.method-get { background-color: var(--success); color: #fff; } +.method-post { background-color: var(--accent); color: #fff; } +.method-patch { background-color: var(--warning); color: #000; } +.method-delete { background-color: var(--error); color: #fff; } + +/* Endpoint path */ +.endpoint { + font-family: 'SF Mono', Monaco, 'Cascadia Code', monospace; + font-size: 0.9rem; + color: var(--text-primary); +} + +/* API section */ +.api-section { + background-color: var(--bg-secondary); + border: 1px solid var(--border-color); + border-radius: 12px; + padding: 24px; + margin: 24px 0; +} + +.api-section h4 { + margin-top: 0; +} + +/* Cards grid */ +.cards { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(250px, 1fr)); + gap: 16px; + margin: 24px 0; +} + +.card { + display: block; + background-color: var(--bg-secondary); + border: 1px solid var(--border-color); + border-radius: 12px; + padding: 20px; + text-decoration: none; + transition: all 0.2s ease; +} + +.card:hover { + border-color: var(--accent); + text-decoration: none; +} + +.card h4 { + color: var(--text-primary); + margin: 0 0 8px; +} + +.card p { + color: var(--text-secondary); + margin: 0; + font-size: 0.9rem; +} + +/* Alert boxes */ +.alert { + padding: 16px; + border-radius: 12px; + margin: 16px 0; + border: 1px solid var(--border-color); +} + +.alert-info { + background-color: var(--bg-secondary); + border-left: 4px solid var(--accent); +} + +.alert-warning { + background-color: var(--bg-secondary); + border-left: 4px solid var(--warning); +} + +.alert-success { + background-color: var(--bg-secondary); + border-left: 4px solid var(--success); +} + +/* Footer */ +footer { + background-color: var(--bg-secondary); + border-top: 1px solid var(--border-color); + padding: 24px 0; + margin-top: 64px; + text-align: center; +} + +footer p { + color: var(--text-muted); + margin: 0; +} + +/* Sidebar layout for docs */ +.docs-layout { + display: grid; + grid-template-columns: 250px 1fr; + gap: 48px; +} + +.sidebar { + position: sticky; + top: 80px; + height: fit-content; +} + +.sidebar ul { + list-style: none; + padding: 0; +} + +.sidebar li { + margin: 0; +} + +.sidebar a { + display: block; + padding: 8px 12px; + color: var(--text-secondary); + border-radius: 8px; + transition: all 0.2s ease; +} + +.sidebar a:hover, +.sidebar a.active { + background-color: var(--bg-tertiary); + color: var(--accent); + text-decoration: none; +} + +.sidebar h4 { + color: var(--text-muted); + font-size: 0.75rem; + text-transform: uppercase; + letter-spacing: 0.05em; + margin: 24px 0 8px; + padding: 0 12px; +} + +.sidebar h4:first-child { + margin-top: 0; +} + +/* Responsive */ +@media (max-width: 768px) { + .docs-layout { + grid-template-columns: 1fr; + } + + .sidebar { + position: static; + border-bottom: 1px solid var(--border-color); + padding-bottom: 24px; + margin-bottom: 24px; + } + + nav { + gap: 12px; + } + + .hero h1 { + font-size: 2rem; + } + + h1 { font-size: 2rem; } + h2 { font-size: 1.5rem; } + h3 { font-size: 1.25rem; } +} From 5f66ccc1f091bf66dae2a7ef10ce9be0bead3e86 Mon Sep 17 00:00:00 2001 From: Coder-soft Date: Sat, 6 Dec 2025 16:27:34 +0500 Subject: [PATCH 02/11] docs: Add comprehensive API reference documentation for Discord Web Bridge. --- docs/api-reference.html | 810 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 810 insertions(+) create mode 100644 docs/api-reference.html diff --git a/docs/api-reference.html b/docs/api-reference.html new file mode 100644 index 0000000..c84d649 --- /dev/null +++ b/docs/api-reference.html @@ -0,0 +1,810 @@ + + + + + + + API Reference - Discord Web Bridge + + + + + +
+
+ + +
+
+ +
+
+ + +
+

API Reference

+

Complete REST API documentation for Discord Web Bridge. All endpoints require authentication via the + X-API-Key header.

+ +
+

Authentication

+

All API requests require the X-API-Key header with your configured API key.

+ 
curl -H "X-API-Key: your_api_key" http://localhost:3000/api/guilds
+ +

Response Format

+

All responses follow a consistent format:

+ 
// Success
+{
+    "success": true,
+    "data": { ... }
+}
+
+// Error
+{
+    "success": false,
+    "error": "Error message",
+    "code": "ERROR_CODE"
+}
+
+ +
+

Guilds

+ +
+

GET /api/guilds

+

List all guilds the bot is in.

+ 
curl -H "X-API-Key: your_key" http://localhost:3000/api/guilds
+
+ +
+

GET /api/guilds/:guildId

+

Get details of a specific guild.

+ 
curl -H "X-API-Key: your_key" http://localhost:3000/api/guilds/123456789
+
+ +
+

GET /api/guilds/:guildId/channels

+

Get all channels in a guild.

+
+ +
+

GET /api/guilds/:guildId/roles

+

Get all roles in a guild.

+
+ +
+

GET /api/guilds/:guildId/emojis

+

Get all emojis in a guild.

+
+ +
+

GET /api/guilds/:guildId/bans

+

Get all bans in a guild.

+
+ +
+

GET /api/guilds/:guildId/invites

+

Get all invites in a guild.

+
+
+ +
+

Channels

+ +
+

GET /api/channels/:channelId

+

Get a channel by ID.

+
+ +
+

POST /api/guilds/:guildId/channels

+

Create a new channel in a guild.

+
Request Body
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeRequiredDescription
namestringYesChannel name (1-100 chars)
typestringYestext, voice, category, announcement, stage, forum
topicstringNoChannel topic (max 1024 chars)
parentIdstringNoCategory ID
positionnumberNoChannel position
nsfwbooleanNoNSFW flag
rateLimitPerUsernumberNoSlowmode (0-21600 seconds)
bitratenumberNoVoice channel bitrate
userLimitnumberNoVoice channel user limit (0-99)
+
+ +
+

PATCH /api/channels/:channelId

+

Edit a channel. All fields are optional.

+
+ +
+

DELETE /api/channels/:channelId

+

Delete a channel.

+
+ +
+

Threads

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodEndpointDescription
POST/api/channels/:channelId/threadsCreate a thread
GET/api/channels/:channelId/threadsGet all threads
POST/api/channels/:channelId/archiveArchive a thread
DELETE/api/channels/:channelId/archiveUnarchive a thread
POST/api/channels/:channelId/lockLock a thread
DELETE/api/channels/:channelId/lockUnlock a thread
+
+ +
+

POST /api/channels/:channelId/clone

+

Clone a channel. Optionally provide a name in the request body.

+
+ +
+

GET /api/channels/:channelId/webhooks

+

Get all webhooks for a channel.

+
+
+ +
+

Messages

+ +
+

GET /api/channels/:channelId/messages

+

Get messages from a channel.

+
Query Parameters
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeDescription
limitnumberNumber of messages (1-100, default: 50)
beforestringGet messages before this ID
afterstringGet messages after this ID
aroundstringGet messages around this ID
+
+ +
+

GET /api/channels/:channelId/messages/pinned

+

Get pinned messages in a channel.

+
+ +
+

GET /api/channels/:channelId/messages/:messageId

+

Get a specific message by ID.

+
+ +
+

POST /api/channels/:channelId/messages

+

Send a message to a channel.

+
Request Body
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeRequiredDescription
contentstringNo*Message content (max 2000 chars)
embedsarrayNo*Array of embed objects
replyTostringNoMessage ID to reply to
ttsbooleanNoText-to-speech
+

*Either content or at least one embed is required.

+
+ +
+

PATCH /api/channels/:channelId/messages/:messageId

+

Edit a message.

+
+ +
+

DELETE /api/channels/:channelId/messages/:messageId

+

Delete a message.

+
+ +
+

POST /api/channels/:channelId/messages/bulk-delete

+

Bulk delete messages. Send messageIds array in body.

+
+ +
+

Reactions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodEndpointDescription
POST/api/channels/:channelId/messages/:messageId/reactions/:emojiAdd reaction
DELETE/api/channels/:channelId/messages/:messageId/reactions/:emojiRemove reaction
DELETE/api/channels/:channelId/messages/:messageId/reactionsRemove all reactions
GET/api/channels/:channelId/messages/:messageId/reactions/:emoji/users + Get reaction users
+
+ +
+

Pins

+ + + + + + + + + + + + + + + + + + + + +
MethodEndpointDescription
POST/api/channels/:channelId/messages/:messageId/pinPin a message
DELETE/api/channels/:channelId/messages/:messageId/pinUnpin a message
+
+ +
+

POST /api/channels/:channelId/messages/:messageId/crosspost

+

Crosspost a message (for announcement channels).

+
+
+ +
+

Members

+ +
+

GET /api/guilds/:guildId/members

+

List all members in a guild.

+
Query Parameters
+ + + + + + + + + + + + + + + +
ParameterTypeDescription
limitnumberMax members to return (default: 1000)
+
+ +
+

GET /api/guilds/:guildId/members/search

+

Search members by username/nickname.

+
Query Parameters
+ + + + + + + + + + + + + + + + + + + + + + + +
ParameterTypeRequiredDescription
qstringYesSearch query
limitnumberNoMax results (default: 20)
+
+ +
+

GET /api/guilds/:guildId/members/:userId

+

Get a specific member.

+
+ +
+

Moderation

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MethodEndpointDescription
POST/api/guilds/:guildId/members/:userId/kickKick member
POST/api/guilds/:guildId/members/:userId/banBan member
DELETE/api/guilds/:guildId/bans/:userIdUnban user
POST/api/guilds/:guildId/members/:userId/timeoutTimeout member
DELETE/api/guilds/:guildId/members/:userId/timeoutRemove timeout
+ +
Ban Request Body
+ + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
reasonstringBan reason (max 512 chars)
deleteMessageSecondsnumberSeconds of messages to delete (0-604800)
+ +
Timeout Request Body
+ + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeRequiredDescription
durationnumberYesDuration in milliseconds
reasonstringNoTimeout reason
+
+ +
+

Member Roles

+ + + + + + + + + + + + + + + + + + + + +
MethodEndpointDescription
PATCH/api/guilds/:guildId/members/:userId/nicknameSet nickname
PATCH/api/guilds/:guildId/members/:userId/rolesModify roles
+ +
Modify Roles Request Body
+ + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
addstring[]Role IDs to add
removestring[]Role IDs to remove
+
+
+ +
+

Roles

+ +
+

GET /api/guilds/:guildId/roles

+

Get all roles in a guild.

+
+ +
+

GET /api/guilds/:guildId/roles/search?name=RoleName

+

Search for a role by name.

+
+ +
+

GET /api/guilds/:guildId/roles/:roleId

+

Get a specific role.

+
+ +
+

POST /api/guilds/:guildId/roles

+

Create a new role.

+
Request Body
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
namestringRole name (max 100 chars)
colornumberColor integer (0-16777215)
hoistbooleanDisplay separately
mentionablebooleanAllow mentions
permissionsstringPermission bitfield
+
+ +
+

PATCH /api/guilds/:guildId/roles/:roleId

+

Edit a role. Same fields as create, plus position.

+
+ +
+

DELETE /api/guilds/:guildId/roles/:roleId

+

Delete a role.

+
+ +
+

GET /api/guilds/:guildId/roles/:roleId/members

+

Get all member IDs with a specific role.

+
+ +
+

PATCH /api/guilds/:guildId/roles/:roleId/permissions

+

Set role permissions. Send permissions (bitfield string) in body.

+
+
+
+
+
+ +
+
+

Discord Web Bridge © 2024 - MIT License

+
+
+ + + + + \ No newline at end of file From 3e1d6134dbdf0b0841cf5453955e0132e43ecc82 Mon Sep 17 00:00:00 2001 From: Coder-soft Date: Sat, 6 Dec 2025 16:29:34 +0500 Subject: [PATCH 03/11] feat: add comprehensive WebSocket event documentation and an empty LLMs list file. --- docs/websocket.html | 550 ++++++++++++++++++++++++++++++++++++++++++++ llms.txt | 135 +++++++++++ 2 files changed, 685 insertions(+) create mode 100644 docs/websocket.html create mode 100644 llms.txt diff --git a/docs/websocket.html b/docs/websocket.html new file mode 100644 index 0000000..ded08e4 --- /dev/null +++ b/docs/websocket.html @@ -0,0 +1,550 @@ + + + + + + + WebSocket Events - Discord Web Bridge + + + + + +
+
+ + +
+
+ +
+
+ + +
+

WebSocket Events

+

Discord Web Bridge provides real-time event streaming via Socket.IO. Subscribe to guilds and receive + Discord events as they happen.

+ +
+

Connection

+

Connect to the WebSocket server using Socket.IO:

+ 
import { io } from 'socket.io-client';
+
+const socket = io('http://localhost:3000', {
+    auth: {
+        apiKey: 'your_api_key'
+    }
+});
+
+socket.on('connect', () => {
+    console.log('Connected to Discord Web Bridge');
+});
+
+socket.on('connect_error', (error) => {
+    console.error('Connection error:', error.message);
+});
+
+socket.on('disconnect', (reason) => {
+    console.log('Disconnected:', reason);
+});
+
+ +
+

Authentication

+

Authentication is required and must be provided in the auth option when connecting: +

+ 
const socket = io('http://localhost:3000', {
+    auth: {
+        apiKey: 'your_secure_api_key'
+    }
+});
+
+ Note: If authentication fails, the connection will be rejected with an error. +
+
+ +
+

Subscribing to Guilds

+

After connecting, subscribe to specific guilds to receive their events:

+ 
// Subscribe to guilds
+socket.emit('subscribe', {
+    guildIds: ['123456789012345678', '987654321098765432']
+});
+
+// Listen for subscription confirmation
+socket.on('subscribed', (data) => {
+    console.log('Subscribed to guilds:', data.guildIds);
+});
+
+// Unsubscribe from guilds
+socket.emit('unsubscribe', {
+    guildIds: ['123456789012345678']
+});
+
+socket.on('unsubscribed', (data) => {
+    console.log('Unsubscribed from guilds:', data.guildIds);
+});
+ +

Listening for Events

+

All Discord events are emitted through the discord event:

+ 
socket.on('discord', (payload) => {
+    console.log('Event:', payload.event);
+    console.log('Guild:', payload.guildId);
+    console.log('Data:', payload.data);
+    
+    // Handle specific events
+    switch (payload.event) {
+        case 'messageCreate':
+            handleNewMessage(payload.data);
+            break;
+        case 'guildMemberAdd':
+            handleMemberJoin(payload.data);
+            break;
+        // ... handle other events
+    }
+});
+
+ +
+

Message Events

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventDescriptionData
messageCreateNew message sentSerializedMessage
messageUpdateMessage edited{ old, new }
messageDeleteMessage deleted{ id, channelId, guildId }
messageDeleteBulkMultiple messages deleted{ ids, channelId, guildId }
messageReactionAddReaction added{ messageId, channelId, userId, reaction }
messageReactionRemoveReaction removed{ messageId, channelId, userId, emoji }
+ +

Message Object

+ 
{
+    "id": "123456789",
+    "channelId": "987654321",
+    "guildId": "111222333",
+    "author": {
+        "id": "444555666",
+        "username": "user",
+        "discriminator": "0",
+        "globalName": "Display Name",
+        "avatar": "abc123",
+        "bot": false
+    },
+    "content": "Hello, world!",
+    "createdAt": "2024-01-01T12:00:00.000Z",
+    "editedAt": null,
+    "embeds": [],
+    "attachments": [],
+    "reactions": [],
+    "pinned": false
+}
+
+ +
+

Member Events

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventDescriptionData
guildMemberAddMember joinedSerializedMember
guildMemberRemoveMember left/kicked{ user, guildId }
guildMemberUpdateMember updated{ old, new }
presenceUpdatePresence changed{ old, new }
userUpdateUser profile updatedSerializedUser
+ +

Member Object

+ 
{
+    "id": "444555666",
+    "displayName": "Display Name",
+    "nickname": "Nickname",
+    "avatar": null,
+    "displayAvatarUrl": "https://cdn.discordapp.com/...",
+    "joinedAt": "2024-01-01T00:00:00.000Z",
+    "roles": ["111222333", "444555666"],
+    "pending": false,
+    "communicationDisabledUntil": null,
+    "user": { ... },
+    "permissions": ["SendMessages", "ViewChannel"]
+}
+
+ +
+

Channel Events

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventDescriptionData
channelCreateChannel createdSerializedChannel
channelUpdateChannel modified{ old, new }
channelDeleteChannel deletedSerializedChannel
channelPinsUpdatePins updated{ channelId, lastPinTimestamp }
threadCreateThread createdSerializedChannel
threadUpdateThread modified{ old, new }
threadDeleteThread deletedSerializedChannel
threadMembersUpdateThread members changedThread member info
+
+ +
+

Role Events

+ + + + + + + + + + + + + + + + + + + + + + + + + +
EventDescriptionData
roleCreateRole createdSerializedRole
roleUpdateRole modified{ old, new }
roleDeleteRole deleted{ id, guildId }
+ +

Role Object

+ 
{
+    "id": "111222333",
+    "name": "Moderator",
+    "color": 3447003,
+    "hexColor": "#3498db",
+    "hoist": true,
+    "position": 5,
+    "permissions": "8589934591",
+    "managed": false,
+    "mentionable": true
+}
+
+ +
+

Guild Events

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventDescriptionData
guildCreateBot joined guildSerializedGuild
guildUpdateGuild modified{ old, new }
guildDeleteBot left/removed{ id, name, unavailable }
guildBanAddUser banned{ guildId, user }
guildBanRemoveUser unbanned{ guildId, user }
guildEmojisUpdateEmojis changedEmoji data
guildIntegrationsUpdateIntegrations changedIntegration data
+
+ +
+

Voice Events

+ + + + + + + + + + + + + + + +
EventDescriptionData
voiceStateUpdateVoice state changed{ old, new }
+ +

Voice State Object

+ 
{
+    "guildId": "111222333",
+    "channelId": "444555666",
+    "userId": "777888999",
+    "member": { ... },
+    "sessionId": "abc123",
+    "deaf": false,
+    "mute": false,
+    "selfDeaf": false,
+    "selfMute": true,
+    "selfVideo": false,
+    "streaming": false,
+    "suppress": false
+}
+
+ +
+

Other Events

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
EventDescriptionData
typingStartUser started typing{ channelId, userId, timestamp, member }
inviteCreateInvite createdInvite data
inviteDeleteInvite deletedInvite data
interactionCreateInteraction receivedInteraction data
+
+ +

Error Handling

+ 
socket.on('error', (error) => {
+    console.error('WebSocket error:', error.message);
+    if (error.code) {
+        console.error('Error code:', error.code);
+    }
+});
+ +

Complete Example

+ 
import { io } from 'socket.io-client';
+
+const socket = io('http://localhost:3000', {
+    auth: { apiKey: 'your_api_key' }
+});
+
+socket.on('connect', () => {
+    console.log('Connected!');
+    socket.emit('subscribe', { guildIds: ['123456789'] });
+});
+
+socket.on('subscribed', ({ guildIds }) => {
+    console.log('Subscribed to:', guildIds);
+});
+
+socket.on('discord', (payload) => {
+    switch (payload.event) {
+        case 'messageCreate':
+            console.log(`[${payload.data.author.username}]: ${payload.data.content}`);
+            break;
+        case 'guildMemberAdd':
+            console.log(`${payload.data.user.username} joined!`);
+            break;
+        case 'guildMemberRemove':
+            console.log(`${payload.data.user.username} left!`);
+            break;
+    }
+});
+
+socket.on('error', console.error);
+socket.on('disconnect', (reason) => console.log('Disconnected:', reason));
+
+
+
+ +
+
+

Discord Web Bridge © 2024 - MIT License

+
+
+ + + + + \ No newline at end of file diff --git a/llms.txt b/llms.txt new file mode 100644 index 0000000..51f59a3 --- /dev/null +++ b/llms.txt @@ -0,0 +1,135 @@ +# Discord Web Bridge + +> A type-safe TypeScript bridge between websites and Discord bots + +## Overview + +Discord Web Bridge provides a REST API and WebSocket interface for full Discord bot capabilities. Built with TypeScript, Express, Socket.IO, and Discord.js. + +## Key Features + +- REST API for all Discord operations +- Real-time WebSocket event streaming via Socket.IO +- Type-safe with Zod validation +- Full Discord.js coverage + +## API Endpoints + +Base URL: `http://localhost:3000` +Authentication: `X-API-Key` header required + +### Guilds +- GET /api/guilds - List all guilds +- GET /api/guilds/:id - Get guild details +- GET /api/guilds/:id/channels - Get guild channels +- GET /api/guilds/:id/roles - Get guild roles +- GET /api/guilds/:id/members - List members +- GET /api/guilds/:id/emojis - Get emojis +- GET /api/guilds/:id/bans - Get bans +- GET /api/guilds/:id/invites - Get invites + +### Channels +- GET /api/channels/:id - Get channel +- POST /api/guilds/:guildId/channels - Create channel +- PATCH /api/channels/:id - Edit channel +- DELETE /api/channels/:id - Delete channel +- POST /api/channels/:id/threads - Create thread +- GET /api/channels/:id/threads - Get threads +- POST /api/channels/:id/clone - Clone channel +- GET /api/channels/:id/webhooks - Get webhooks + +### Messages +- GET /api/channels/:id/messages - Get messages +- GET /api/channels/:id/messages/pinned - Get pinned messages +- GET /api/channels/:id/messages/:msgId - Get specific message +- POST /api/channels/:id/messages - Send message +- PATCH /api/channels/:id/messages/:msgId - Edit message +- DELETE /api/channels/:id/messages/:msgId - Delete message +- POST /api/channels/:id/messages/bulk-delete - Bulk delete +- POST /api/channels/:id/messages/:msgId/reactions/:emoji - Add reaction +- DELETE /api/channels/:id/messages/:msgId/reactions/:emoji - Remove reaction +- POST /api/channels/:id/messages/:msgId/pin - Pin message +- DELETE /api/channels/:id/messages/:msgId/pin - Unpin message +- POST /api/channels/:id/messages/:msgId/crosspost - Crosspost message + +### Members +- GET /api/guilds/:id/members - List members +- GET /api/guilds/:id/members/search?q=query - Search members +- GET /api/guilds/:id/members/:userId - Get member +- POST /api/guilds/:id/members/:userId/kick - Kick member +- POST /api/guilds/:id/members/:userId/ban - Ban member +- DELETE /api/guilds/:id/bans/:userId - Unban user +- PATCH /api/guilds/:id/members/:userId/nickname - Set nickname +- PATCH /api/guilds/:id/members/:userId/roles - Modify roles +- POST /api/guilds/:id/members/:userId/timeout - Timeout member +- DELETE /api/guilds/:id/members/:userId/timeout - Remove timeout + +### Roles +- GET /api/guilds/:id/roles - List roles +- GET /api/guilds/:id/roles/search?name=name - Search roles +- GET /api/guilds/:id/roles/:roleId - Get role +- POST /api/guilds/:id/roles - Create role +- PATCH /api/guilds/:id/roles/:roleId - Edit role +- DELETE /api/guilds/:id/roles/:roleId - Delete role +- GET /api/guilds/:id/roles/:roleId/members - Get role members +- PATCH /api/guilds/:id/roles/:roleId/permissions - Set permissions + +## WebSocket Events + +Connect via Socket.IO with authentication: + +```javascript +const socket = io('http://localhost:3000', { + auth: { apiKey: 'your_key' } +}); + +socket.emit('subscribe', { guildIds: ['123456789'] }); + +socket.on('discord', (event) => { + console.log(event.event, event.data); +}); +``` + +### Available Events +- messageCreate, messageUpdate, messageDelete, messageDeleteBulk +- messageReactionAdd, messageReactionRemove +- guildMemberAdd, guildMemberRemove, guildMemberUpdate +- presenceUpdate, userUpdate +- channelCreate, channelUpdate, channelDelete +- threadCreate, threadUpdate, threadDelete +- roleCreate, roleUpdate, roleDelete +- voiceStateUpdate +- guildBanAdd, guildBanRemove +- typingStart +- inviteCreate, inviteDelete + +## Configuration + +Environment variables: +- DISCORD_TOKEN - Discord bot token (required) +- API_KEY - API authentication key (required) +- PORT - Server port (default: 3000) +- DEBUG - Enable debug logging (default: false) + +## Quick Start + +```bash +npm install +cp .env.example .env +# Edit .env with your values +npm run dev +``` + +## File Structure + +- src/index.ts - Entry point +- src/api/server.ts - Express server setup +- src/api/routes/ - REST API routes +- src/api/websocket/ - WebSocket event handlers +- src/discord/ - Discord.js client and services +- src/types/ - TypeScript type definitions +- docs/ - HTML documentation + +## License + +MIT From 150bfc97078e171f49a9035da8c3626ceadb0d36 Mon Sep 17 00:00:00 2001 From: Coder-soft Date: Sat, 6 Dec 2025 17:38:50 +0500 Subject: [PATCH 04/11] feat: Introduce core application logic and a new documentation site with API reference and WebSocket event details. --- .env.example | 2 +- README.md | 2 +- docs/api-reference.html | 13 +++++++------ docs/getting-started.html | 10 +++++----- docs/index.html | 27 +++++++++++++++++---------- docs/styles.css | 2 +- docs/websocket.html | 16 ++++++++-------- llms.txt | 4 ++-- src/index.ts | 6 +++--- 9 files changed, 45 insertions(+), 37 deletions(-) diff --git a/.env.example b/.env.example index 6fa90ff..4cce0cb 100644 --- a/.env.example +++ b/.env.example @@ -1,4 +1,4 @@ -# Discord Web Bridge - Environment Variables +# Holo Bridge - Environment Variables # Discord Bot Token (required) # Get this from https://discord.com/developers/applications diff --git a/README.md b/README.md index b5a1acc..5035b48 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Discord Web Bridge +# Holo Bridge A type-safe TypeScript bridge between websites and Discord bots. Provides a REST API and WebSocket interface for full Discord bot capabilities. diff --git a/docs/api-reference.html b/docs/api-reference.html index c84d649..6f3ee42 100644 --- a/docs/api-reference.html +++ b/docs/api-reference.html @@ -4,15 +4,15 @@ - API Reference - Discord Web Bridge - + API Reference - Holo Bridge +
- +