fakecord.js

Official JavaScript/TypeScript SDK for building FakeCord bots.

Works with fakecord.pl and self-hosted instances.

What you can build

• Message bots (Gateway events + low-latency sending)
• Moderation bots (timeouts, roles, permissions)
• Server automation (channels/categories/voice, server settings)
• Custom slash commands (simple /command args style interactions)

Installation

npm install fakecord.js

Requires Node.js 18+.

ESM (recommended)

import { Client } from 'fakecord.js';

Use "type": "module" in your package.json, or save the file as .mjs.

CommonJS

const { Client } = require('fakecord.js');

Works on Node 18+ with the require export (v0.1.1+).

Create a bot

Option A — Developer Portal (recommended)

1. Log in at fakecord.pl
2. Open fakecord.pl/dev-portal
3. Click Create bot and copy the fcbot_… token immediately
4. Generate an OAuth invite link and share it
5. The receiver opens the link and selects a server (Manage Server permission required)

Option B — REST API

curl -X POST https://fakecord.pl/api/bots \
  -H "Content-Type: application/json" \
  -H "Cookie: fc_session=YOUR_SESSION" \
  -d '{"name":"MyBot"}'

Response:

{
  "id": "...",
  "publicId": 1,
  "name": "MyBot",
  "userId": "...",
  "token": "fcbot_..."
}

The token is returned only once. Store it securely.

OAuth invite link (shareable)

Generate a link (as bot owner):

curl https://fakecord.pl/api/bots/BOT_ID/invite-url \
  -H "Cookie: fc_session=YOUR_SESSION"

Open/share the returned url:

https://fakecord.pl/oauth2/authorize?client_id=123&scope=bot

The person who opens the link chooses the server and must have Manage Server.

Quick start

import { Client } from 'fakecord.js';

const client = new Client({
  token: process.env.FAKECORD_BOT_TOKEN,
  apiBase: 'https://fakecord.pl',
});

client.on('ready', (user) => {
  console.log(`Logged in as ${user.username}`);
});

client.on('messageCreate', async (message) => {
  if (message.content === '!ping') {
    await client.send(message.channelId, 'Pong!');
  }
});

await client.login();

Save as bot.mjs and run:

FAKECORD_BOT_TOKEN=fcbot_... node bot.mjs

Authentication

Bots authenticate with:

Authorization: Bot fcbot_xxxxxxxx

The same token works for REST and WebSocket (Gateway).

Client API

Constructor

new Client({
  token: string;       // fcbot_… token
  apiBase?: string;    // default: https://fakecord.pl
})

Methods

| Method | Description | |--------|-------------| | login() | Authenticate and connect Gateway | | send(channelId, content) | Send message via WebSocket (lowest latency) | | sendToChannel(serverPublicId, channelPublicId, options) | Send via REST | | fetchGuilds() | List servers the bot can access | | fetchGuild(serverPublicId) | Read server details | | setGuildSettings(serverPublicId, { name, vanityCode }) | Update server name/vanity | | fetchChannels(serverPublicId) | List channels | | createChannel(serverPublicId, { name, type, parentId }) | Create text/voice/category channel | | updateChannel(serverPublicId, channelPublicId, patch) | Update channel name/parent/position | | deleteChannel(serverPublicId, channelPublicId) | Delete channel | | fetchMembers(serverPublicId) | List members | | timeoutMember(serverPublicId, userId, minutes) | Timeout (mute) a member | | removeTimeout(serverPublicId, userId) | Remove timeout | | fetchRoles(serverPublicId) | List roles | | createRole(serverPublicId, role) | Create role (name/color/perms/etc.) | | updateRole(serverPublicId, roleId, patch) | Update role (name/color/perms/etc.) | | deleteRole(serverPublicId, roleId) | Delete role | | setMemberRoles(serverPublicId, userId, roleIds) | Assign roles to a member | | setGuildIcon(serverPublicId, buffer, contentType) | Upload server icon | | setGuildBanner(serverPublicId, buffer, contentType) | Upload server banner | | uploadEmoji(serverPublicId, buffer, contentType) | Upload emoji image (returns URL) | | joinChannel(channelId) | Join channel room for guaranteed events |

Slash commands

FakeCord slash commands are delivered as an interaction event when someone sends:

/commandName args...

Register commands for your bot:

await client.application.commands.set([
  { name: 'ping', description: 'Replies with Pong' },
]);

Handle them:

client.on('interactionCreate', async (i) => {
  if (i.commandName === 'ping') {
    await i.reply('Pong!');
  }
});

Events

| Event | Payload | Description | |-------|---------|-------------| | ready | User | Bot connected | | messageCreate | Message | New channel message | | messageUpdate | Message | Message edited or enriched | | messageDelete | { id, channelId } | Message removed | | interactionCreate | Interaction | Slash command interaction | | disconnect | — | Socket disconnected |

REST vs Gateway

| Transport | Use when | |-----------|----------| | Gateway (client.send) | Real-time bots, lowest latency | | REST (client.sendToChannel) | Simple scripts, no persistent connection |

For reliable event delivery, call joinChannel after login:

const channels = await client.fetchChannels(1);
await client.joinChannel(channels[0].id);

Example: moderation bot

import { Client } from 'fakecord.js';

const client = new Client({
  token: process.env.FAKECORD_BOT_TOKEN,
  apiBase: 'https://fakecord.pl',
});

client.on('messageCreate', async (msg) => {
  if (msg.content.includes('badword')) {
    await client.send(msg.channelId, 'Please keep chat friendly.');
  }
});

await client.login();

Self-hosted instances

Point apiBase to your server:

const client = new Client({
  token: process.env.FAKECORD_BOT_TOKEN,
  apiBase: 'http://localhost:3001',
});

Development (this repo)

cd packages/fakecord
npm install
npm run build

Link locally:

npm link
cd ../../my-bot-project
npm link fakecord.js

Publish to npm

npm requires two-factor authentication or a granular access token with publish rights.

1. Enable 2FA at npmjs.com
2. Build the package:

cd packages/fakecord
npm run build

3. Publish:

npm publish --access public --otp=YOUR_6_DIGIT_CODE

For updates, bump version in package.json and publish again.

Scoped package (alternative)

"name": "@yourname/fakecord"

npm publish --access public

Troubleshooting

| Issue | Solution | |-------|----------| | 403 on publish | Enable npm 2FA or use a publish token | | Unauthorized | Check token starts with fcbot_ and header is Bot … | | No messageCreate events | Call joinChannel(channelId) after login | | Bot not in server | Generate OAuth invite link and authorize it on /oauth2/authorize | | Logged in as undefined | Update to [email protected]+ |

License

MIT