@mostfeatured/dbi 0.2.17 → 0.2.18

package/docs/llm/EVENTS.txt

@@ -1,449 +0,0 @@
-================================================================================
-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
-================================================================================