loopbot-discord-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,406 @@
+# LoopBot SDK TypeScript
+
+The official library for building LoopBot bots using TypeScript/JavaScript.
+
+## Installation
+
+```bash
+npm install loopbot-sdk
+```
+
+## Initialization
+
+```typescript
+import { Bot } from 'loopbot-sdk';
+
+const bot = new Bot({
+    token: 'your_token_here'
+});
+
+// ... your commands here ...
+
+bot.start();
+```
+
+## Complete Guide
+
+### Working with Embeds
+
+Embeds are rich messages that allow you to display information in a structured way.
+
+```typescript
+import { EmbedBuilder } from 'loopbot-sdk';
+
+bot.command('embed_demo', 'Embed Demo', (ctx) => {
+    // Creating an embed
+    const embed = new EmbedBuilder()
+        .setTitle('Embed Title')
+        .setDescription('Detailed description here...')
+        .setColor(0x00FF00) // Hex color (e.g., Green)
+        .setURL('https://loopbot.app')
+        .setFooter('Footer Text', 'https://example.com/icon.png')
+        .setAuthor('Author Name', 'https://profile.com', 'https://avatar.com/img.png')
+        .setImage('https://example.com/large_image.png')
+        .setThumbnail('https://example.com/thumbnail.png')
+        .addField('Field 1', 'Value 1', true) // inline = true
+        .addField('Field 2', 'Value 2', true)
+        .setTimestamp(); // Uses current time if not specified
+
+    // Sending the embed
+    ctx.reply({ embeds: [embed] });
+});
+```
+
+### Working with Containers (Components V2)
+
+Containers are advanced components that allow you to visually group other components like text, separators, and galleries.
+
+> **Note:** To send containers, use the `replyWithComponents` or `updateWithComponents` methods.
+
+```typescript
+import { ContainerBuilder, SeparatorBuilder, MediaGalleryBuilder } from 'loopbot-sdk';
+
+bot.command('container_demo', 'Container Demo', (ctx) => {
+    // Creating a container
+    const container = new ContainerBuilder()
+        .setAccentColor(0xFF0000) // Sidebar color
+        .setSpoiler(false) // Whether content is a spoiler
+        .addText('# Title inside Container')
+        .addText('This is normal text inside the container.');
+
+    // Adding a Separator
+    // spacing: 1 (small) or 2 (large)
+    container.addSeparator(true, 1);
+
+    // Adding a Media Gallery
+    const gallery = new MediaGalleryBuilder()
+        .addItem('https://example.com/img1.png', 'Caption 1')
+        .addItem('https://example.com/img2.png', 'Caption 2');
+        
+    container.addComponent(gallery);
+
+    // Sending the container
+    ctx.replyWithComponents({ components: [container] });
+});
+```
+
+### Separators
+
+Separators help visually organize content within containers or as standalone components.
+
+```typescript
+import { SeparatorBuilder } from 'loopbot-sdk';
+
+// Separator with visible line and large spacing
+const sep = new SeparatorBuilder()
+    .setDivider(true)
+    .setSpacing(2);
+
+// Can be added to a container
+container.addComponent(sep);
+```
+
+### Replying to Interactions
+
+The context (`ctx`) provides various methods to respond to commands and interactions.
+
+#### Reply with Text and Embeds
+
+```typescript
+// Text only
+ctx.reply({ content: 'Hello world!' });
+
+// Text and Embed
+ctx.reply({ 
+    content: 'Check this out:', 
+    embeds: [embed] 
+});
+
+// Ephemeral response (visible only to the user who ran the command)
+ctx.reply({ 
+    content: 'Secret...', 
+    ephemeral: true 
+});
+```
+
+#### Reply with Components V2 (Containers)
+
+To send Containers, Galleries, or Separators as the main response.
+
+```typescript
+ctx.replyWithComponents({ components: [container1, container2] });
+```
+
+#### Updating the Original Message
+
+Useful for button or select menu interactions where you want to change the original message instead of sending a new one.
+
+```typescript
+bot.onButton('my_button', (ctx) => {
+    // Update text and embeds of the message where the button was
+    const embed = new EmbedBuilder().setTitle('Updated!');
+    
+    ctx.update({ 
+        content: 'New message', 
+        embeds: [embed] 
+    });
+
+    // Or to update with Containers
+    // ctx.updateWithComponents({ components: [newContainer] });
+});
+```
+
+#### Editing the Response (Follow-up)
+
+If you have already replied (e.g., with `defer` or a quick response) and want to edit that response later.
+
+```typescript
+bot.command('process', 'Long processing', async (ctx) => {
+    // Acknowledge processing
+    ctx.defer();
+    
+    // ... long processing ...
+    
+    // Edit the original response
+    await ctx.editReply({ 
+        content: 'Processing complete!', 
+        embeds: [resultEmbed] 
+    });
+});
+```
+
+### Buttons and Action Rows
+
+Buttons are interactive components that users can click. They must be placed inside an `ActionRow`.
+
+```typescript
+import { ActionRowBuilder, ButtonBuilder, ButtonStyle } from 'loopbot-sdk';
+
+bot.command('buttons', 'Button demo', (ctx) => {
+    // Creating buttons
+    const btnPrimary = new ButtonBuilder()
+        .setLabel('Click here')
+        .setCustomId('btn_click')
+        .setStyle(ButtonStyle.PRIMARY); // Blue
+
+    const btnLink = new ButtonBuilder()
+        .setLabel('Visit Website')
+        .setURL('https://loopbot.app')
+        .setStyle(ButtonStyle.LINK); // Gray
+
+    // Adding to ActionRow
+    const row = new ActionRowBuilder()
+        .addButton(btnPrimary)
+        .addButton(btnLink);
+
+    ctx.reply({ content: 'Choose an option:', components: [row] });
+});
+
+bot.onButton('btn_click', (ctx) => {
+    ctx.reply({ content: 'You clicked the button!', ephemeral: true });
+});
+```
+
+### Select Menus (Dropdowns)
+
+Select menus allow users to choose one or more options from a list.
+
+```typescript
+import { SelectMenuBuilder, ActionRowBuilder } from 'loopbot-sdk';
+
+bot.command('menu', 'Menu demo', (ctx) => {
+    const select = new SelectMenuBuilder()
+        .setCustomId('select_menu')
+        .setPlaceholder('Choose your class')
+        .addOption('Warrior', 'warrior', 'Melee combat class')
+        .addOption('Mage', 'mage', 'Magic class', { name: '🔮' })
+        .setMinValues(1)
+        .setMaxValues(1);
+
+    const row = new ActionRowBuilder().addSelectMenu(select);
+    ctx.reply({ content: 'Select your class:', components: [row] });
+});
+
+bot.onSelect('select_menu', (ctx) => {
+    const value = ctx.values[0];
+    ctx.reply({ content: `You selected: ${value}`, ephemeral: true });
+});
+```
+
+### Modals (Forms)
+
+Modals are pop-up windows with forms for text input.
+
+```typescript
+import { ModalBuilder } from 'loopbot-sdk';
+
+bot.command('feedback', 'Send feedback', (ctx) => {
+    const modal = new ModalBuilder()
+        .setCustomId('feedback_modal')
+        .setTitle('Give us your feedback')
+        .addTextInput(
+            'input_msg',
+            'Message',
+            'paragraph', // or 'short'
+            {
+                placeholder: 'Write here...',
+                required: true
+            }
+        );
+    
+    ctx.showModal(modal);
+});
+```
+
+### Advanced Layout (Sections)
+
+Sections allow you to group text with a side "accessory" like a button or image.
+
+```typescript
+import { SectionBuilder, ButtonBuilder, ButtonStyle } from 'loopbot-sdk';
+
+bot.command('section', 'Section Demo', (ctx) => {
+    const btn = new ButtonBuilder()
+        .setLabel('See More')
+        .setURL('https://google.com')
+        .setStyle(ButtonStyle.LINK);
+
+    const section = new SectionBuilder()
+        .addText('**Section Title**')
+        .addText('Detailed description next to the button.')
+        .setButtonAccessory(btn);
+
+    ctx.replyWithComponents({ components: [section] });
+});
+```
+
+### Files
+
+Sending files as attachments or within structures.
+
+```typescript
+import { FileBuilder } from 'loopbot-sdk';
+
+const file = new FileBuilder('https://example.com/file.pdf').setSpoiler(false);
+// Add to a container or send as supported by API
+```
+
+## Quick Reference
+
+| Feature | Builder / Method |
+| :--- | :--- |
+| **Embed** | `EmbedBuilder` |
+| **Container** | `ContainerBuilder` |
+| **Separator** | `SeparatorBuilder` |
+| **Gallery** | `MediaGalleryBuilder` |
+| **Button** | `ButtonBuilder` |
+| **Action Row** | `ActionRowBuilder` |
+| **Select Menu** | `SelectMenuBuilder` |
+| **Modal** | `ModalBuilder` |
+| **Section** | `SectionBuilder` |
+| **File** | `FileBuilder` |
+| **Reply** | `ctx.reply(...)` |
+| **Reply (Container)** | `ctx.replyWithComponents(...)` |
+| **Update Msg** | `ctx.update(...)` |
+| **Edit Reply** | `ctx.editReply(...)` |
+
+## Direct Messaging API
+
+Send messages outside of interaction context, manage channels, roles, and more.
+
+### Sending Messages
+
+```typescript
+// Send a message to any channel
+await bot.send(channelId, { content: 'Hello!' });
+
+// Edit a message
+await bot.editMessage(channelId, messageId, { content: 'Updated!' });
+
+// Delete a message
+await bot.deleteMessage(channelId, messageId);
+```
+
+### Channel Management
+
+```typescript
+// Create a channel
+await bot.createChannel(guildId, { name: 'new-channel', topic: 'Description' });
+
+// Modify a channel
+await bot.modifyChannel(channelId, { name: 'renamed-channel' });
+
+// Delete a channel
+await bot.deleteChannel(channelId);
+```
+
+### Forum Channels
+
+```typescript
+// Create a forum post
+await bot.createForumPost(forumChannelId, {
+    name: 'My Post Title',
+    message: { content: 'Post content here' },
+    applied_tags: ['tagId']
+});
+
+// Get/modify forum tags
+const tags = await bot.getForumTags(forumChannelId);
+await bot.modifyForumTags(forumChannelId, [{ name: 'New Tag' }]);
+
+// Archive/lock threads
+await bot.archiveThread(threadId);
+await bot.lockThread(threadId);
+```
+
+### Roles
+
+```typescript
+// Get roles
+const roles = await bot.getRoles(guildId);
+
+// Create a role
+await bot.createRole(guildId, { name: 'Moderator', color: 0x00FF00 });
+
+// Modify a role
+await bot.modifyRole(guildId, roleId, { name: 'Admin', hoist: true });
+
+// Delete a role
+await bot.deleteRole(guildId, roleId);
+
+// Reorder roles
+await bot.reorderRoles(guildId, [{ id: roleId, position: 2 }]);
+```
+
+### Webhooks
+
+```typescript
+// Create a webhook
+const webhook = await bot.createWebhook(channelId, { name: 'My Webhook' });
+
+// Send message via webhook
+await bot.executeWebhook(webhookId, webhookToken, {
+    content: 'Message via webhook!',
+    username: 'Custom Name'
+});
+
+// Edit/delete webhook message
+await bot.editWebhookMessage(webhookId, webhookToken, messageId, { content: 'Updated' });
+await bot.deleteWebhookMessage(webhookId, webhookToken, messageId);
+
+// Delete webhook
+await bot.deleteWebhook(webhookId);
+```
+
+### Member Management
+
+```typescript
+// Add/remove roles
+await bot.addMemberRole(guildId, userId, roleId);
+await bot.removeMemberRole(guildId, userId, roleId);
+
+// Kick/ban members
+await bot.kickMember(guildId, userId);
+await bot.banMember(guildId, userId);
+```
+