@mostfeatured/dbi 0.2.13 → 0.2.15

package/docs/llm/EVENTS.txt

@@ -0,0 +1,449 @@
+================================================================================
+DBI - EVENTS GUIDE - LLM REFERENCE DOCUMENT
+================================================================================
+
+DOCUMENT TYPE: Event System Reference
+PACKAGE: @mostfeatured/dbi
+
+================================================================================
+SECTION 1: BASIC EVENTS
+================================================================================
+
+SIMPLE EVENT HANDLER:
+---------------------
+dbi.register(({ Event }) => {
+  Event({
+    name: "clientReady",
+    id: "ready-logger",
+    onExecute({ client }) {
+      console.log(`Bot is online as ${client.user.tag}`);
+      console.log(`Serving ${client.guilds.cache.size} guilds`);
+    }
+  });
+});
+
+EVENT PARAMETERS FORMAT:
+------------------------
+Event parameters are received in an object format:
+
+// Message events
+Event({
+  name: "messageCreate",
+  id: "message-logger",
+  onExecute({ message }) {
+    if (message.author.bot) return;
+    console.log(`${message.author.tag}: ${message.content}`);
+  }
+});
+
+// Member events
+Event({
+  name: "guildMemberAdd",
+  id: "welcome-handler",
+  async onExecute({ member }) {
+    const channel = member.guild.systemChannel;
+    if (channel) {
+      await channel.send(`Welcome ${member}!`);
+    }
+  }
+});
+
+// Reaction events
+Event({
+  name: "messageReactionAdd",
+  id: "reaction-roles",
+  onExecute({ reaction, user }) {
+    if (user.bot) return;
+    console.log(`${user.tag} reacted with ${reaction.emoji.name}`);
+  }
+});
+
+================================================================================
+SECTION 2: COMMON EVENTS REFERENCE
+================================================================================
+
+EVENT NAME          | PARAMETERS                    | DESCRIPTION
+--------------------|-------------------------------|------------------------
+clientReady         | { client }                    | Bot connected and ready
+messageCreate       | { message }                   | New message received
+messageDelete       | { message }                   | Message was deleted
+messageUpdate       | { oldMessage, newMessage }    | Message was edited
+guildCreate         | { guild }                     | Bot joined a guild
+guildDelete         | { guild }                     | Bot left a guild
+guildMemberAdd      | { member }                    | Member joined guild
+guildMemberRemove   | { member }                    | Member left guild
+guildMemberUpdate   | { oldMember, newMember }      | Member updated
+interactionCreate   | { interaction }               | Any interaction received
+voiceStateUpdate    | { oldState, newState }        | Voice state changed
+channelCreate       | { channel }                   | Channel created
+channelDelete       | { channel }                   | Channel deleted
+roleCreate          | { role }                      | Role created
+roleDelete          | { role }                      | Role deleted
+
+================================================================================
+SECTION 3: MULTIPLE EVENT HANDLERS
+================================================================================
+
+You can register multiple handlers for the same event using unique IDs:
+
+dbi.register(({ Event }) => {
+  // First handler - logging
+  Event({
+    name: "messageCreate",
+    id: "message-logger",
+    onExecute({ message }) {
+      console.log(`Message: ${message.id}`);
+    }
+  });
+  
+  // Second handler - auto-moderation
+  Event({
+    name: "messageCreate",
+    id: "auto-mod",
+    onExecute({ message }) {
+      if (containsBadWords(message.content)) {
+        message.delete();
+      }
+    }
+  });
+  
+  // Third handler - leveling system
+  Event({
+    name: "messageCreate",
+    id: "leveling",
+    async onExecute({ message }) {
+      if (message.author.bot) return;
+      await addXP(message.author.id, 10);
+    }
+  });
+});
+
+TOGGLING EVENT HANDLERS:
+------------------------
+const handler = dbi.event("togglable-logger");
+
+handler.toggle();       // Toggle state
+handler.toggle(true);   // Disable
+handler.toggle(false);  // Enable
+
+console.log(handler.disabled);  // Check state
+
+================================================================================
+SECTION 4: EVENT CONFIGURATION
+================================================================================
+
+TRIGGER TYPES (for multi-client):
+---------------------------------
+Event({
+  name: "messageCreate",
+  id: "my-handler",
+  triggerType: "OneByOneGlobal",  // Default
+  onExecute({ message, nextClient }) {
+    console.log(`Handled by: ${nextClient?.namespace}`);
+  }
+});
+
+TRIGGER TYPE OPTIONS:
+---------------------
+TYPE            | DESCRIPTION
+----------------|------------------------------------------
+OneByOne        | Each client triggers sequentially
+OneByOneGlobal  | Global sequential (default)
+Random          | Random client handles
+First           | First client only
+
+ORDERED EXECUTION:
+------------------
+Event({
+  name: "messageCreate",
+  id: "ordered-handler",
+  ordered: {
+    await: true,        // Wait for async completion
+    delayBefore: 100,   // Wait 100ms before executing
+    delayAfter: 50      // Wait 50ms after executing
+  },
+  async onExecute({ message }) {
+    await doAsyncWork(message);
+  }
+});
+
+CONDITIONAL LOADING WITH FLAGS:
+-------------------------------
+Event({
+  name: "messageCreate",
+  id: "debug-logger",
+  flag: "debug",
+  onExecute({ message }) {
+    console.log("[DEBUG]", message);
+  }
+});
+
+// Load with debug events
+await dbi.load("debug");
+
+// Load without debug events
+await dbi.load();
+
+EVENT TTL (INLINE EVENTS):
+--------------------------
+createInlineEvent({
+  name: "messageCreate",
+  ttl: 60000,  // Auto-remove after 1 minute
+  onExecute({ message }) {
+    if (message.content === "special") {
+      message.reply("You found it!");
+    }
+  }
+});
+
+================================================================================
+SECTION 5: CUSTOM EVENTS
+================================================================================
+
+DEFINING CUSTOM EVENTS:
+-----------------------
+dbi.register(({ CustomEvent, Event }) => {
+  // Define custom event structure
+  CustomEvent({
+    name: "userLevelUp",
+    map: {
+      userId: "userId",
+      newLevel: "newLevel",
+      guild: "guild"
+    }
+  });
+  
+  // Listen for custom event
+  Event({
+    name: "userLevelUp",
+    id: "levelup-announcer",
+    onExecute({ userId, newLevel, guild }) {
+      const channel = guild.systemChannel;
+      if (channel) {
+        channel.send(`<@${userId}> reached level ${newLevel}!`);
+      }
+    }
+  });
+});
+
+TRIGGERING CUSTOM EVENTS:
+-------------------------
+dbi.emit("userLevelUp", {
+  userId: "123456789",
+  newLevel: 10,
+  guild: someGuild
+});
+
+// Or using the returned object
+const levelUpEvent = CustomEvent({
+  name: "playerLevelUp",
+  map: { playerId: "playerId", level: "level", rewards: "rewards" }
+});
+
+levelUpEvent.trigger({
+  playerId: "12345",
+  level: 5,
+  rewards: ["gold", "exp_boost"]
+});
+
+================================================================================
+SECTION 6: DBI INTERNAL EVENTS
+================================================================================
+
+AVAILABLE DBI EVENTS:
+---------------------
+EVENT                                    | DESCRIPTION
+-----------------------------------------|----------------------------
+clientsReady                             | All clients connected
+beforeInteraction                        | Before handling interaction
+afterInteraction                         | After handling interaction
+interactionError                         | Error during interaction
+interactionRateLimit                     | Rate limit triggered
+beforeEvent                              | Before event handler
+afterEvent                               | After event handler
+eventError                               | Error during event
+messageCommandArgumentError              | Invalid message command arg
+messageCommandDirectMessageUsageError    | DM command not allowed
+messageCommandDefaultMemberPermissionsError | Missing permissions
+
+BEFORE/AFTER INTERACTION:
+-------------------------
+dbi.events.on("beforeInteraction", async (ctx) => {
+  console.log(`Interaction: ${ctx.dbiInteraction.name}`);
+  console.log(`User: ${ctx.interaction.user.tag}`);
+  return true;  // Return true to continue, false to stop
+});
+
+dbi.events.on("afterInteraction", async (ctx) => {
+  console.log(`Completed: ${ctx.dbiInteraction.name}`);
+  return true;
+});
+
+ERROR HANDLING:
+---------------
+dbi.events.on("interactionError", async ({ interaction, dbiInteraction, error }) => {
+  console.error(`Error in ${dbiInteraction.name}:`, error);
+  
+  try {
+    if (interaction.replied || interaction.deferred) {
+      await interaction.followUp({
+        content: "An error occurred.",
+        ephemeral: true
+      });
+    } else {
+      await interaction.reply({
+        content: "An error occurred.",
+        ephemeral: true
+      });
+    }
+  } catch (e) {
+    console.error("Could not send error message:", e);
+  }
+  return true;
+});
+
+dbi.events.on("eventError", async ({ eventName, dbiEvent, error }) => {
+  console.error(`Error in event ${eventName}:`, error);
+  return true;
+});
+
+RATE LIMITING:
+--------------
+dbi.events.on("interactionRateLimit", async ({ 
+  interaction, 
+  dbiInteraction, 
+  rateLimit,
+  remainingTime 
+}) => {
+  const seconds = Math.ceil(remainingTime / 1000);
+  
+  await interaction.reply({
+    content: `Slow down! Try again in ${seconds} seconds.`,
+    ephemeral: true
+  });
+  
+  return false;  // Don't execute the interaction
+});
+
+MESSAGE COMMAND ERRORS:
+-----------------------
+const { ApplicationCommandOptionType } = require("discord.js");
+
+dbi.events.on("messageCommandArgumentError", ({ 
+  message, interaction, dbiInteraction, error 
+}) => {
+  message.reply(
+    `Invalid argument \`${error.option.name}\` (Index: ${error.index}).\n` +
+    `Error: \`${error.type}\`\n` +
+    `Expected: \`${ApplicationCommandOptionType[error.option.type]}\``
+  );
+  return false;
+});
+
+dbi.events.on("messageCommandDirectMessageUsageError", ({ message }) => {
+  message.reply("This command cannot be used in DMs.");
+  return false;
+});
+
+dbi.events.on("messageCommandDefaultMemberPermissionsError", ({ message, permissions }) => {
+  message.reply(`You need these permissions: ${permissions.join(", ")}`);
+  return false;
+});
+
+ONE-TIME EVENT HANDLERS:
+------------------------
+dbi.events.on("clientsReady", () => {
+  console.log("Bot is ready!");
+}, { once: true });
+
+REMOVING EVENT HANDLERS:
+------------------------
+const removeHandler = dbi.events.on("beforeInteraction", (ctx) => {
+  console.log("Interaction received");
+  return true;
+});
+
+// Later, remove the handler
+removeHandler();
+
+================================================================================
+SECTION 7: EVENT FLOW
+================================================================================
+
+INTERACTION FLOW:
+1. Discord sends interaction
+2. beforeInteraction event fires
+3. Rate limit check
+4. interactionRateLimit event if limited
+5. Interaction handler executes
+6. afterInteraction event fires
+7. If error: interactionError event fires
+
+EVENT FLOW:
+1. Discord sends event
+2. beforeEvent event fires
+3. Event handler executes
+4. afterEvent event fires
+5. If error: eventError event fires
+
+================================================================================
+SECTION 8: BEST PRACTICES
+================================================================================
+
+// GOOD - Use specific event IDs
+Event({
+  name: "messageCreate",
+  id: "spam-filter-v1",
+  onExecute({ message }) { /* ... */ }
+});
+
+// BAD - Missing ID causes conflicts
+Event({
+  name: "messageCreate",
+  // No ID - will throw error if strict mode is on
+  onExecute({ message }) { /* ... */ }
+});
+
+// GOOD - Return early from bot messages
+Event({
+  name: "messageCreate",
+  id: "my-handler",
+  onExecute({ message }) {
+    if (message.author.bot) return;
+    // Handle user messages
+  }
+});
+
+// GOOD - Use async/await properly
+Event({
+  name: "guildMemberAdd",
+  id: "welcome",
+  async onExecute({ member }) {
+    try {
+      await member.send("Welcome!");
+    } catch (error) {
+      console.error("Could not DM member:", error);
+    }
+  }
+});
+
+================================================================================
+SECTION 9: GUILD LOCALE IN EVENTS
+================================================================================
+
+dbi.register(({ Event }) => {
+  Event({
+    name: "messageCreate",
+    id: "localized-response",
+    onExecute({ message, locale }) {
+      if (message.content === "!hello") {
+        const greeting = locale?.guild?.data?.greeting?.() || "Hello!";
+        message.reply(greeting);
+      }
+    }
+  });
+});
+
+================================================================================
+END OF DOCUMENT
+================================================================================