Bleucord

A comprehensive Discord API v10 library for the BleuMoon Luau runtime.

Features

• Full Discord API v10 coverage — REST endpoints, Gateway WebSocket, OAuth2
• High-level Client — event-driven bot framework with automatic caching
• Low-level access — direct REST client and Gateway shard control
• Builder pattern — fluent APIs for embeds, components, slash commands, modals
• Auto-sharding — concurrency-aware shard spawning via /gateway/bot
• Rate limiting — per-route bucket management with automatic retry
• Typed — --!strict mode throughout with full type annotations
• Voice support — voice gateway protocol (audio transport is a placeholder — BleuMoon has no UDP API)
• OAuth2 — Discord OAuth2 flows via BleuAuth

Quick Start

local bleucord = require("@pkg/bleucord/src")
local Client = bleucord.Client
local Intents = bleucord.Intents

local client = Client.new({
	intents = Intents.DEFAULT,
})

client:on("READY", function(data)
	print(`Logged in as {data.user.username}!`)
end)

client:on("MESSAGE_CREATE", function(message)
	if message.content == "!ping" then
		client.rest:post(`/channels/{message.channel_id}/messages`, {
			body = { content = "Pong!" },
		})
	end
end)

client:login("YOUR_BOT_TOKEN")

Installation

Add bleucord as a dependency in your bleumoon.toml:

[dependencies]
bleucord = "*"

Then install:

bleumoon pkg install

Prerequisites

• BleuMoon v2.0.0 or later
• StyLua (for code formatting, optional)

Tip: If you have Nix with flakes enabled, both tools are provided automatically via nix develop.

Documentation

• Getting Started Guide
• API Reference
• Slash Commands Guide
• Message Components Guide
• Embeds Guide

Development

Setup

git clone https://git.ds.reinitialized.net/bleupigs.club/bleucord.git
cd bleucord
nix develop          # or install BleuMoon + StyLua manually
bleumoon pkg install

Running Tests

bleumoon run tests/init

437 unit tests covering utilities, structures, builders, gateway, cache, and OAuth modules.

Formatting

stylua --check .   # check
stylua .           # apply

Project Structure

├── bleumoon.toml          # Project manifest & dependencies
├── src/
│   ├── init.luau          # Library entry point (exports)
│   ├── main.luau          # Example application entry point
│   ├── client/            # High-level Client class
│   ├── rest/              # REST client & endpoint modules
│   │   └── endpoints/     # 18 endpoint modules (guild, channel, message, etc.)
│   ├── gateway/           # WebSocket gateway, sharding, heartbeat, intents
│   ├── structures/        # Builders: embed, component, command, permission, snowflake
│   ├── cache/             # CacheManager & 9 typed store modules
│   │   └── stores/        # guild, channel, member, role, user, message, etc.
│   ├── events/            # EventEmitter, event name constants
│   ├── voice/             # Voice gateway, connection, audio player
│   ├── oauth/             # Discord OAuth2 via BleuAuth
│   └── utils/             # Bitfield, Collection, CDN, errors, constants
├── tests/
│   ├── init.luau          # BleuTest-based test runner
│   └── unit/              # 17 unit test files
├── types/
│   └── discord.luau       # Comprehensive Discord API type definitions
├── docs/
│   ├── api/               # API reference documentation
│   ├── guides/            # Usage guides
│   ├── architecture/      # Architecture Decision Records
│   └── investigations/    # Bug investigation write-ups
└── packages/              # Installed dependencies (auto-managed, gitignored)

Known Limitations

• Voice audio transport is a placeholder — BleuMoon does not currently expose a UDP API. The voice gateway handshake works, but sending/receiving audio frames requires UDP.
• Interaction signature verification uses a placeholder — BleuMoon's crypto module doesn't support Ed25519 signing.
• Large snowflake shard calculation uses string-based modular arithmetic to avoid double-precision overflow.

License

This project is licensed under the MIT License.