botads-api/readme.md

Module to earn money on your projects by displaying ads

# Bot-Ads

**Bot-Ads** is a library that allows you to share your projects and/or earn money by displaying ads in your Discord bot. With Bot-Ads you can generate advertisement links, create attractive ad embeds, and track ad clicks using unique codes.

## Installation

Install the package via npm:

```bash
npm install botads-api
```

## Usage

Below is an example of how to integrate Bot-Ads into your Discord bot:

```js
const { Client, GatewayIntentBits } = require('discord.js');
const BotAds = require('botads-api');

// Initialize BotAds with the user ID that will receive the ad revenue.
// Optionally, enable debug mode by passing 'true' as the second parameter.
const adSystem = new BotAds("123456789", true);

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent
  ]
});

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

client.on('messageCreate', async (message) => {
  // Ignore bot messages and messages outside servers.
  if (message.author.bot || !message.guild) return;

  // Command to retrieve an ad link.
  if (message.content.toLowerCase() === '!ad-link') {
    const adLinkData = await adSystem.getAdLink('uniqueCode');
    if (adLinkData && adLinkData.success) {
      message.channel.send(`🔗 Ad Link: ${adLinkData.redirect_url}`);
    } else {
      message.channel.send(":x: Unable to retrieve an ad link at the moment.");
    }
  }

  // Command to generate an ad embed.
  if (message.content.toLowerCase() === '!ad-embed') {
    const adEmbedData = await adSystem.generateAdEmbed(0x0099FF, 'uniqueCode');
    if (adEmbedData && adEmbedData.success) {
      message.channel.send({ embeds: [adEmbedData.embed] });
    } else {
      message.channel.send(":x: Unable to generate an ad embed at the moment.");
    }
  }

  // Command to check if the ad has been clicked.
  if (message.content.toLowerCase() === '!check-ad') {
    const checkData = await adSystem.checkCode('uniqueCode');
    if (checkData && checkData.success) {
      if (checkData.clicked) {
        message.channel.send("✅ The ad has been clicked!");
      } else {
        message.channel.send("ℹ️ The ad has not been clicked yet.");
      }
    } else {
      message.channel.send(":x: Unable to verify the ad click status at the moment.");
    }
  }
});

client.login('YOUR_BOT_TOKEN');
```

---


## API Methods

### `getAdLink(code?: string): Promise<AdLinkResponse | null>`

Retrieves an advertisement link from the Bot-Ads API.

- **Parameters:**
  - `code` (optional): A tracking code to associate with the advertisement.
- **Returns:**
  - On success:  
    ```js
    { 
      success: true, 
      ad_id?: string, 
      description?: string, 
      redirect_url?: string 
    }
    ```
  - On failure: `null`

---


### `generateAdEmbed(color?: number, code?: string): Promise<AdEmbedResponse>`

Generates an embed containing the advertisement.

- **Parameters:**
  - `color` (optional): The embed color as a hexadecimal number (default is `0x0099FF`).
  - `code` (optional): A tracking code to associate with the advertisement.
- **Returns:**
  - On success:  
    ```js
    { 
      success: true, 
      link?: string, 
      embed?: object 
    }
    ```
  - On failure:  
    ```js
    { 
      success: false, 
      message: "Error message" 
    }
    ```

---


### `checkCode(code: string): Promise<CheckCodeResponse | null>`

Checks if a user has clicked on the advertisement associated with the provided tracking code.

- **Parameters:**
  - `code`: The tracking code to verify.
- **Returns:**
  - On success:  
    ```js
    { 
      success: true, 
      clicked?: boolean 
    }
    ```
  - On failure: `null`

---


### `setDebug(value: boolean): void`

Enables or disables debug mode.

- **Parameters:**
  - `value`: `true` to enable debug mode, `false` to disable it.

---


### `getUserId(): string`

Returns the user ID that was used to initialize BotAds.

---


## Complete Example

Below is a complete example demonstrating all available functions of Bot-Ads:

```js
const { Client, GatewayIntentBits } = require('discord.js');
const BotAds = require('botads-api');

// Initialize the Discord client with necessary intents.
const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent
  ]
});

// Initialize BotAds with the user ID that will receive the revenue and enable debug mode.
const adSystem = new BotAds("123456789", true);

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

client.on('messageCreate', async (message) => {
  // Ignore bot messages and messages outside a server.
  if (message.author.bot || !message.guild) return;

  // Command to retrieve an ad link.
  if (message.content.toLowerCase() === '!ad-link') {
    try {
      const adLinkData = await adSystem.getAdLink('uniqueCode');
      if (adLinkData && adLinkData.success) {
        message.channel.send(`🔗 Ad Link: ${adLinkData.redirect_url}`);
      } else {
        message.channel.send(":x: Unable to retrieve an ad link at the moment.");
      }
    } catch (error) {
      console.error("Error with getAdLink:", error);
      message.channel.send(":x: An error occurred while retrieving the ad link.");
    }
  }

  // Command to generate an ad embed.
  if (message.content.toLowerCase() === '!ad-embed') {
    try {
      const adEmbedData = await adSystem.generateAdEmbed(0x0099FF, 'uniqueCode');
      if (adEmbedData && adEmbedData.success) {
        message.channel.send({ embeds: [adEmbedData.embed] });
      } else {
        message.channel.send(":x: Unable to generate an ad embed at the moment.");
      }
    } catch (error) {
      console.error("Error with generateAdEmbed:", error);
      message.channel.send(":x: An error occurred while generating the ad embed.");
    }
  }

  // Command to check if the ad has been clicked.
  if (message.content.toLowerCase() === '!check-ad') {
    try {
      const checkData = await adSystem.checkCode('uniqueCode');
      if (checkData && checkData.success) {
        if (checkData.clicked) {
          message.channel.send("✅ The ad has been clicked!");
        } else {
          message.channel.send("ℹ️ The ad has not been clicked yet.");
        }
      } else {
        message.channel.send(":x: Unable to verify the ad click status at the moment.");
      }
    } catch (error) {
      console.error("Error with checkCode:", error);
      message.channel.send(":x: An error occurred while checking the ad click.");
    }
  }
});

client.login('YOUR_BOT_TOKEN');
```

---


## Important Notices

- **User ID**: Replace `"123456789"` with the actual user ID that will receive the ad revenue. If the user ID is incorrect, please [contact support](https://discord.gg/G6kDDjYhtq).
- **Tracking Codes**: Use unique tracking codes (e.g., `uniqueCode`) to monitor user interactions with your ads.
- **Embed Color**: You can specify the embed color as a hexadecimal number (e.g., `0x0099FF`). A default value of `0x0099FF` is used if no color is provided.
- **Debug Mode**: Enable debug mode for more detailed error logging by passing `true` as the second argument when creating a new instance of BotAds.

---


## Documentation

For further details on all functionalities, please refer to our [documentation](https://wiki.bot-ads.ovh/).

---


## Author

**Bot-Ads** is developed and maintained by **milleniumishere**.

---


## Contact

- **Discord Support Server:** [Join Here](https://discord.gg/G6kDDjYhtq)
- **Email:** [support@bot-ads.ovh](mailto:support@bot-ads.ovh)

---


## License

This library is licensed under the **MIT License**. See the [LICENSE](./LICENSE) file for more details.

---


This README should give users a clear understanding of how to install, configure, and utilize the Bot-Ads module within their Discord bot projects.