Discord

Lightweight, dependency-free, in-memory fake of the Discord REST API (v10) for testing code that uses the real discord.js client (and any HTTP client that speaks the Discord REST protocol).

Default port: 4655

Quick start

Start the server:

import { DiscordServer } from "./services/discord/src/server.js";

const server = new DiscordServer(4655);
await server.start();
// ... run your app/tests ...
await server.stop();

Point the real discord.js REST client at it. The client reads its base URL from the api option (it appends /v{version} itself), so override it to the parlel fake:

import { REST } from "discord.js"; // or "@discordjs/rest"
import { Routes } from "discord-api-types/v10";

const rest = new REST({ version: "10" })
  .setToken("parlel.test.discordbottoken");

// Override the API base so requests hit the parlel fake instead of discord.com:
rest.options.api = "http://127.0.0.1:4655/api";

// Who am I?
const me = await rest.get(Routes.user("@me"));
// me.id === "1000000000000000010", me.username === "parlelbot"

// Send a message
const msg = await rest.post(Routes.channelMessages("3000000000000000001"), {
  body: { content: "hello from parlel" },
});
// msg.content === "hello from parlel", msg.author.id === me.id

// Register a slash command
await rest.put(
  Routes.applicationCommands("1000000000000000001"),
  { body: [{ name: "ping", description: "Ping!" }] },
);

The full Client (with the WebSocket Gateway) is not emulated — see the unsupported table below. Use the REST client (or raw fetch) for REST flows, which is what client.guilds, channel.send(), command deployment, etc. use under the hood.

Every guild, channel, message, member, role, ban, emoji, webhook, invite, reaction, and thread is captured in memory and can be inspected via the /__parlel/* endpoints (see below). The whole world is resettable.

Wire protocol

• REST routes live under /api and /api/v{n} (v6–v10 accepted; the prefix is optional).
• Auth via Authorization: Bot <token> (a Bearer token is also accepted). Webhook execution / webhook-token routes carry the token in the URL and need no header.
• JSON request and response bodies. multipart/form-data uploads are parsed best-effort via their payload_json part.
• IDs are Discord-shaped snowflakes (stringified, monotonically increasing).
• Success responses use the appropriate status (200, 201, or 204 No Content).
• Errors use Discord's envelope: HTTP 4xx/5xx with { "message": string, "code": number, "errors"?: object }.
• X-Audit-Log-Reason is accepted (and ignored) on mutating routes.
• Informational X-RateLimit-* headers are sent; the fake never actually rate-limits.

Seeded fixtures

On startup / reset the world contains:

Valid tokens: parlel.test.discordbottoken, parlel.test.discordbottoken.bot.

Implemented operations / endpoints

Gateway

• GET /gateway
• GET /gateway/bot

OAuth2 / application identity

• GET /oauth2/applications/@me
• GET /oauth2/@me

Users

• GET /users/@me
• PATCH /users/@me
• GET /users/{user.id}
• GET /users/@me/guilds
• GET /users/@me/guilds/{guild.id}/member
• DELETE /users/@me/guilds/{guild.id} (leave guild)
• GET /users/@me/channels
• POST /users/@me/channels (open / reuse a DM)

Channels

• GET /channels/{channel.id}
• PATCH /channels/{channel.id}
• DELETE /channels/{channel.id}
• POST /channels/{channel.id}/typing
• POST /channels/{channel.id}/followers
• GET / POST /channels/{channel.id}/invites
• PUT / DELETE /channels/{channel.id}/permissions/{overwrite.id}
• GET / POST /channels/{channel.id}/webhooks

Messages

• GET /channels/{channel.id}/messages
• POST /channels/{channel.id}/messages
• GET /channels/{channel.id}/messages/{message.id}
• PATCH /channels/{channel.id}/messages/{message.id}
• DELETE /channels/{channel.id}/messages/{message.id}
• POST /channels/{channel.id}/messages/bulk-delete
• POST /channels/{channel.id}/messages/{message.id}/crosspost
• replies via message_reference

Reactions

• PUT /channels/{channel.id}/messages/{message.id}/reactions/{emoji}/@me
• DELETE /channels/{channel.id}/messages/{message.id}/reactions/{emoji}/@me
• DELETE /channels/{channel.id}/messages/{message.id}/reactions/{emoji}/{user.id}
• GET /channels/{channel.id}/messages/{message.id}/reactions/{emoji} (list reactors)
• DELETE /channels/{channel.id}/messages/{message.id}/reactions/{emoji} (clear one emoji)
• DELETE /channels/{channel.id}/messages/{message.id}/reactions (clear all)
• Unicode (🔥) and custom (name:id) emoji are both supported.
• The reactions array embedded in a message uses the full Discord v10 Reaction object shape: { count, count_details: { burst, normal }, me, me_burst, emoji, burst_colors }.

Pins

• GET /channels/{channel.id}/pins
• PUT /channels/{channel.id}/pins/{message.id}
• DELETE /channels/{channel.id}/pins/{message.id}

Threads

• POST /channels/{channel.id}/threads (standalone thread)
• POST /channels/{channel.id}/messages/{message.id}/threads (thread from a message)
• GET /channels/{thread.id}/thread-members
• GET /channels/{thread.id}/thread-members/{user.id|@me}
• PUT /channels/{thread.id}/thread-members/{user.id}
• DELETE /channels/{thread.id}/thread-members/{user.id}

Guilds

• POST /guilds
• GET /guilds/{guild.id} (supports ?with_counts=true)
• PATCH /guilds/{guild.id}
• DELETE /guilds/{guild.id}
• GET /guilds/{guild.id}/preview
• GET / POST /guilds/{guild.id}/prune
• GET /guilds/{guild.id}/invites
• GET /guilds/{guild.id}/webhooks

Guild channels

• GET /guilds/{guild.id}/channels
• POST /guilds/{guild.id}/channels
• PATCH /guilds/{guild.id}/channels (bulk reposition)

Guild members

• GET /guilds/{guild.id}/members
• GET /guilds/{guild.id}/members/search?query=
• GET /guilds/{guild.id}/members/{user.id|@me}
• PUT /guilds/{guild.id}/members/{user.id} (add member — 201 with the member body when created, 204 No Content when the user is already a member)
• PATCH /guilds/{guild.id}/members/{user.id} (nick / roles / mute / deaf / timeout)
• DELETE /guilds/{guild.id}/members/{user.id} (kick)
• PUT / DELETE /guilds/{guild.id}/members/{user.id}/roles/{role.id}

Guild roles

• GET /guilds/{guild.id}/roles
• POST /guilds/{guild.id}/roles
• PATCH /guilds/{guild.id}/roles (bulk reposition)
• PATCH /guilds/{guild.id}/roles/{role.id}
• DELETE /guilds/{guild.id}/roles/{role.id} (also detaches from members)

Guild bans

• GET /guilds/{guild.id}/bans
• GET /guilds/{guild.id}/bans/{user.id}
• PUT /guilds/{guild.id}/bans/{user.id} (also removes membership)
• DELETE /guilds/{guild.id}/bans/{user.id}

Guild emojis

• GET /guilds/{guild.id}/emojis
• POST /guilds/{guild.id}/emojis
• GET /guilds/{guild.id}/emojis/{emoji.id}
• PATCH /guilds/{guild.id}/emojis/{emoji.id}
• DELETE /guilds/{guild.id}/emojis/{emoji.id}

Invites (top-level)

• GET /invites/{code}
• DELETE /invites/{code}

Webhooks

• GET /webhooks/{webhook.id}
• PATCH /webhooks/{webhook.id}
• DELETE /webhooks/{webhook.id}
• GET /webhooks/{webhook.id}/{token}
• PATCH /webhooks/{webhook.id}/{token}
• DELETE /webhooks/{webhook.id}/{token}
• POST /webhooks/{webhook.id}/{token} (execute; ?wait=true returns the message, otherwise 204)
• GET /webhooks/{webhook.id}/{token}/messages/{message.id|@original}
• PATCH /webhooks/{webhook.id}/{token}/messages/{message.id|@original}
• DELETE /webhooks/{webhook.id}/{token}/messages/{message.id|@original}

Application (slash) commands

• GET / POST / PUT /applications/{app.id}/commands
• GET / PATCH / DELETE /applications/{app.id}/commands/{command.id}
• GET / POST / PUT /applications/{app.id}/guilds/{guild.id}/commands
• GET / PATCH / DELETE /applications/{app.id}/guilds/{guild.id}/commands/{command.id}

parlel control / inspection endpoints (not part of Discord)

• POST /__parlel/reset — wipe all state back to the seeded defaults.
• GET /__parlel/messages — every stored message across channels.
• GET /__parlel/channels — every channel/thread.
• GET /__parlel/guilds — every guild (with roles + emojis).
• POST /__parlel/users — add a User fixture (e.g. { "username": "bob" }).
• GET /health — { "status": "ok" }.
• GET / — service descriptor.

Surface coverage

This emulator faithfully replicates the API surface most application code and agents exercise. Anything below the supported lines is either an intentional design choice for a fast, zero-cost local emulator (✓ By design) or a candidate for a future release (⟳ Roadmap) — never a silent inaccuracy.

Legend: ✅ fully supported · ◐ accepted (stored, not strictly enforced) · ✓ by design · ⟳ on the roadmap.

Error codes / shapes

All errors return the Discord envelope:

{ "message": "Unknown Channel", "code": 10003 }

Validation errors additionally include an errors object:

{
  "message": "Invalid Form Body",
  "code": 50035,
  "errors": {
    "name": { "_errors": [{ "code": "BASE_TYPE_REQUIRED", "message": "This field is required" }] }
  }
}

Tests

tests/discord.test.ts starts the server on port 14655, drives every implemented operation (happy paths plus key edge cases) through a faithful discord.js-style REST client mirror, and tears the server down in afterAll. Run it with:

npx vitest run tests/discord.test.ts

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

DISCORD_TOKEN=parlel.test.discordbottoken
DISCORD_BOT_TOKEN=parlel.test.discordbottoken
DISCORD_APPLICATION_ID=1000000000000000001
DISCORD_API_BASE_URL=http://parlel-bridge:4655/api/v10