dcmaker-studio

Oficjalne SDK do tworzenia i integracji botów Discord z panelem DCMAKER Studio. SDK stanowi nakładkę na bibliotekę discord.js i pozwala na łatwiejsze pisanie kodu z użyciem prostych i skróconych funkcji, przy jednoczesnym zachowaniu pełnego dostępu do natywnego klienta Discord.js.

🔒 Bezpieczeństwo Tokenu Discord

[!IMPORTANT] Token bota Discord i klucz DCMAKER Studio to dwa osobne parametry. Twój token bota Discord służy wyłącznie do lokalnego logowania bota i autoryzacji w bramie Discorda. NIGDY nie jest on przesyłany do serwerów API DCMAKER ani zapisywany w bazie danych panelu. Cała komunikacja z panelem DCMAKER Studio odbywa się przy użyciu bezpiecznego klucza API (dcm_live_...).

1. Instalacja

Zainstaluj paczkę npm wraz z niezbędną zależnością peer-dependency discord.js:

npm install dcmaker-studio discord.js

2. Konfiguracja .env

Utwórz plik .env w głównym katalogu swojego bota:

DISCORD_TOKEN=twoj_token_bota_discord
DCMAKER_API_KEY=dcm_live_twoj_klucz_dcmaker_studio
DISCORD_GUILD_ID=twoj_id_serwera_discord

3. Pierwszy bot

Oto minimalny kod potrzebny do uruchomienia bota:

import "dotenv/config";
import { createBot } from "dcmaker-studio";

const bot = createBot({
  token: process.env.DISCORD_TOKEN!,
  apiKey: process.env.DCMAKER_API_KEY!,
  guildId: process.env.DISCORD_GUILD_ID,
  intents: ["guilds", "members", "messages", "messageContent"],
});

bot.on("ready", (client) => {
  console.log(`Bot ${client.user?.tag} działa!`);
});

await bot.start();

4. Tworzenie komend (Slash Commands)

Metoda bot.cmd() automatycznie rejestruje komendy slash na Discordzie (lokalnie dla serwera guildId lub globalnie, jeśli go nie podano).

bot.cmd(
  "ban",
  async (ctx) => {
    const user = ctx.user("member");
    const reason = ctx.string("reason") || "Brak powodu";

    if (!user) {
      return ctx.reply("Musisz wskazać użytkownika.");
    }

    await ctx.ban(user, reason);
    await ctx.reply(`Zbanowano użytkownika <@${user.id}> z powodu: ${reason}`);
  },
  {
    description: "Banuje użytkownika z serwera",
    permissions: ["BanMembers"],
    options: [
      {
        name: "member",
        description: "Użytkownik do zbanowania",
        type: "user",
        required: true,
      },
      {
        name: "reason",
        description: "Powód nałożenia bana",
        type: "string",
        required: false,
      },
    ],
  }
);

Kontekst komendy (ctx) dostarcza:

• Właściwości: ctx.interaction, ctx.userId, ctx.guildId, ctx.channelId, ctx.member, ctx.guild.
• Odpowiedzi: ctx.reply(), ctx.privateReply(), ctx.defer(), ctx.edit(), ctx.followUp().
• Pobieranie opcji: ctx.string(), ctx.number(), ctx.boolean(), ctx.user(), ctx.channel(), ctx.role().
• Akcje moderacyjne: ctx.ban(), ctx.kick(), ctx.timeout().

5. Obsługa zdarzeń (Events)

Możesz nasłuchiwać zdarzeń za pomocą wygodnych aliasów lub bezpośrednio przez dowolny event discord.js.

Skrócone aliasy (bot.on):

bot.on("ready", (client) => { /* bot uruchomiony */ });
bot.on("join", (member) => { /* guildMemberAdd */ });
bot.on("leave", (member) => { /* guildMemberRemove */ });
bot.on("message", (message) => { /* messageCreate */ });
bot.on("guildCreate", (guild) => { /* dodanie bota do serwera */ });
bot.on("guildDelete", (guild) => { /* usunięcie bota z serwera */ });
bot.on("interaction", (interaction) => { /* nowa interakcja */ });

Dowolne zdarzenia Discord.js (bot.event):

bot.event("messageReactionAdd", (reaction, user) => {
  console.log(`${user.tag} dodał reakcję ${reaction.emoji.name}`);
});

6. Wysyłanie wiadomości i embedów

// Wysyłanie zwykłej wiadomości (szuka po ID kanału lub nazwie)
await bot.send("general", "Witajcie na kanale generalnym!");

// Wysyłanie bogatych wiadomości Embed
await bot.embed("announcements", {
  title: "📢 Nowa aktualizacja!",
  description: "Zaimplementowaliśmy oficjalne SDK DCMAKER Studio.",
  color: "#5865F2",
  footer: { text: "DCMAKER.pl" }
});

7. Zarządzanie rolami

SDK pozwala na szybkie dodawanie i usuwanie ról:

// Dodawanie roli użytkownikowi
await bot.role.add(memberId, roleId);

// Usuwanie roli
await bot.role.remove(memberId, roleId);

8. Moderacja użytkowników

Wygodne metody do moderowania serwera bez konieczności ręcznego fetchowania obiektów z discord.js:

// Zbanowanie użytkownika
await bot.member.ban(memberId, "Naruszenie regulaminu");

// Wyrzucenie użytkownika
await bot.member.kick(memberId, "Spam");

// Wyciszenie (Timeout) na czas określony (np. "10m", "1h", "2d")
await bot.member.timeout(memberId, "10m", "Przeklinanie");

9. Konfiguracja z panelu DCMAKER

Możesz synchronizować i pobierać konfiguracje zapisane dla Twojego bota w panelu DCMAKER Studio:

// Pobranie aktualnie zaimportowanej konfiguracji
const config = await bot.configManager.get();

// Ręczna weryfikacja i synchronizacja najnowszych danych
const freshConfig = await bot.configManager.sync();

10. Obsługa błędów

SDK udostępnia dedykowane klasy błędów do kontrolowania przepływu aplikacji:

import {
  StudioError,
  StudioApiError,
  InvalidApiKeyError,
  RevokedApiKeyError,
  MissingScopeError,
  DiscordActionError
} from "@dcmaker/studio";

try {
  await bot.member.ban("1234", "Powód");
} catch (error) {
  if (error instanceof InvalidApiKeyError) {
    console.error("Podany klucz API jest błędny!");
  } else if (error instanceof DiscordActionError) {
    console.error("Błąd podczas banowania na Discordzie:", error.message);
  } else {
    console.error("Wystąpił inny błąd:", error);
  }
}

11. Bezpieczeństwo i tolerancja awarii (Fault Tolerance)

W przypadku chwilowej awarii lub niedostępności API DCMAKER Studio, podstawowe funkcje bota Discord będą działać dalej bez zakłóceń. Obejmuje to:

• Rejestrowanie i obsługę komend slash (bot.cmd),
• Reagowanie na zdarzenia (bot.on / bot.event),
• Wysyłanie wiadomości oraz embedów,
• Zarządzanie członkami i rolami.

Metody zintegrowane bezpośrednio z panelem (np. wysyłanie logów serwera czy analityki) nie przerwą wykonywania kodu bota w przypadku niepowodzenia połączenia z serwerem, zapobiegając wyłączeniu bota.