aifordiscord-api

An advanced npm package for Discord bots providing AI-enhanced random content, memes, jokes, and utilities with comprehensive documentation.

🚀 Features

• AI-Enhanced Content: Powered by OpenAI for improved jokes, advice, facts, and custom content
• Comprehensive API: 15+ content types including memes, jokes, advice, anime images, facts, quotes, animal images, trivia, and more
• Built-in Caching: Intelligent caching system to reduce API calls
• Rate Limiting: Built-in rate limiting to prevent abuse
• TypeScript Support: Full TypeScript definitions included
• Easy Integration: Simple Discord.js integration
• Error Handling: Robust error handling and validation
• Customizable: Flexible configuration options
• GitHub Integration: Fetch user information from GitHub
• Trivia Questions: Multiple choice questions with difficulty levels
• Animal Images: Random dog and cat images
• Inspirational Content: Quotes, compliments, and affirmations

📦 Installation

1npm install aifordiscord-api

🚀 Quick Start

1const { AIForDiscord } = require('aifordiscord-api');
2
3// Basic usage (no AI features)
4const random = new AIForDiscord();
5
6// With AI enhancement (requires OpenAI API key)
7const random = new AIForDiscord({
8  openaiApiKey: 'your-openai-key',
9  enableAI: true,
10  enableCache: true
11});
12
13// Get a meme
14const meme = await random.getMeme();
15console.log(meme.title, meme.url);
16
17// Get advice
18const advice = await random.getAdvice();
19console.log(advice.advice);

📚 API Reference

Basic Content Methods

getMeme()

Returns a random meme from Reddit with metadata.

1const data = await random.getMeme();
2message.channel.send({
3  embeds: [{
4    title: data.title,
5    image: { url: data.url },
6    url: data.postLink,
7    footer: { text: `r/${data.subreddit} • ${data.ups} upvotes` }
8  }]
9});

Returns: MemeResponse

1{
2  title: string;
3  url: string;
4  postLink: string;
5  subreddit: string;
6  author: string;
7  nsfw: boolean;
8  spoiler: boolean;
9  ups: number;
10}

getAdvice()

Provides random advice with optional AI enhancement.

1const data = await random.getAdvice();
2message.channel.send(`💡 **Advice:** ${data.advice}`);

Returns: AdviceResponse

1{
2  advice: string;
3  slip_id: number;
4}

getNeko()

Provides a random neko (cat girl) image.

1const data = await random.getNeko();
2message.channel.send({
3  embeds: [{
4    title: '🐱 Random Neko',
5    image: { url: data.url }
6  }]
7});

Returns: NekoResponse

1{
2  url: string;
3}

getRandomJoke()

Provides a random funny joke with optional AI enhancement.

1const data = await random.getRandomJoke();
2if (data.type === 'twopart') {
3  message.channel.send(`${data.setup}\n\n||${data.delivery}||`);
4} else {
5  message.channel.send(data.joke);
6}

Returns: JokeResponse

1{
2  setup?: string;
3  delivery?: string;
4  joke?: string;
5  category: string;
6  type: string;
7  safe: boolean;
8  id: number;
9}

getNameJoke(firstName, lastName?)

Provides a random funny joke related to the given name.

1const data = await random.getNameJoke("John", "Doe");
2message.channel.send(`😄 ${data.joke}`);

Parameters:

• firstName (string): Required first name
• lastName (string, optional): Last name

Returns: NameJokeResponse

1{
2  joke: string;
3  name: string;
4  enhanced: boolean;
5}

getAnimeImgURL(type)

Provides a random anime image URL based on action type.

1const data = await random.getAnimeImgURL("hug");
2message.channel.send({
3  embeds: [{
4    title: `🤗 ${data.type.toUpperCase()}`,
5    image: { url: data.url }
6  }]
7});

Parameters:

• type (string): Action type - "pat", "hug", "waifu", "cry", "kiss", "slap", "smug", "punch"

Returns: AnimeImageResponse

1{
2  url: string;
3  type: string;
4}

getFact()

Provides a random fact with optional AI enhancement.

1const data = await random.getFact();
2message.channel.send(`🧠 **Did you know?**\n${data.fact}`);

Returns: FactResponse

1{
2  fact: string;
3  source?: string;
4  enhanced: boolean;
5}

getNPM(packageName)

Provides information about an NPM package.

1const data = await random.getNPM("discord.js");
2message.channel.send({
3  embeds: [{
4    title: `📦 ${data.name}`,
5    description: data.description,
6    fields: [
7      { name: 'Version', value: data.version, inline: true },
8      { name: 'Author', value: data.author || 'Unknown', inline: true }
9    ]
10  }]
11});

getQuote()

Provides a random inspirational quote.

1const data = await random.getQuote();
2message.channel.send(`💭 **"${data.quote}"** - *${data.author}*`);

getDogImage()

Provides a random dog image.

1const data = await random.getDogImage();
2message.channel.send({
3  embeds: [{
4    title: '🐕 Random Dog',
5    image: { url: data.url }
6  }]
7});

getCatImage()

Provides a random cat image.

1const data = await random.getCatImage();
2message.channel.send({
3  embeds: [{
4    title: '🐱 Random Cat',
5    image: { url: data.url }
6  }]
7});

getTrivia(category?, difficulty?)

Provides a trivia question with multiple choice answers.

1const data = await random.getTrivia();
2const answers = data.answers.map((answer, index) => `${index + 1}. ${answer}`).join('\n');
3message.channel.send(`🧠 **Trivia Time!**\n\n${data.question}\n\n${answers}`);

getDadJoke()

Provides a random dad joke.

1const data = await random.getDadJoke();
2message.channel.send(`👨 **Dad Joke:** ${data.joke}`);

getChuckNorrisJoke()

Provides a random Chuck Norris joke.

1const data = await random.getChuckNorrisJoke();
2message.channel.send(`💪 **Chuck Norris:** ${data.joke}`);

getCompliment()

Provides a random compliment.

1const data = await random.getCompliment();
2message.channel.send(`😊 ${data.compliment}`);

getAffirmation()

Provides a positive affirmation.

1const data = await random.getAffirmation();
2message.channel.send(`✨ ${data.affirmation}`);

getGitHubUser(username)

Provides information about a GitHub user.

1const data = await random.getGitHubUser("octocat");
2message.channel.send({
3  embeds: [{
4    title: `👨‍💻 ${data.name || data.username}`,
5    description: data.bio,
6    thumbnail: { url: data.avatarUrl },
7    fields: [
8      { name: 'Followers', value: data.followers.toString(), inline: true },
9      { name: 'Following', value: data.following.toString(), inline: true },
10      { name: 'Public Repos', value: data.publicRepos.toString(), inline: true }
11    ],
12    url: data.htmlUrl
13  }]
14});

AI-Enhanced Methods

generateCustomJoke(topic) 🤖

Generates a custom joke using AI on a specific topic (requires OpenAI API key).

1const joke = await random.generateCustomJoke("programming");
2message.channel.send(`🤖 ${joke}`);

Parameters:

• topic (string): Topic for the joke

Returns: string - AI-generated joke

Utility Methods

clearCache()

Clears the internal cache.

1random.clearCache();

getConfig()

Returns current configuration.

1const config = random.getConfig();
2console.log('AI enabled:', config.enableAI);

isAIEnabled()

Checks if AI features are enabled and available.

1if (random.isAIEnabled()) {
2  console.log('AI features are ready!');
3}

⚙️ Configuration Options

1const random = new AIForDiscord({
2  openaiApiKey: 'your-openai-key',    // OpenAI API key for AI features
3  enableCache: true,                   // Enable caching (default: true)
4  cacheTimeout: 300000,               // Cache timeout in ms (default: 5 minutes)
5  enableRateLimit: true,              // Enable rate limiting (default: true)
6  rateLimitRequests: 100,             // Max requests per window (default: 100)
7  rateLimitWindow: 60000,             // Rate limit window in ms (default: 1 minute)
8  enableAI: true,                     // Enable AI enhancement (default: true)
9  contentFilter: true                 // Enable content filtering (default: true)
10});

🤖 AI Features

When an OpenAI API key is provided, the package offers enhanced content:

• Enhanced Jokes: Makes jokes funnier and more engaging
• Enhanced Advice: Provides more thoughtful and actionable advice
• Enhanced Facts: Makes facts more interesting while maintaining accuracy
• Custom Jokes: Generate completely custom jokes on any topic
• Name Personalization: Better integration of names into jokes

📁 Complete Examples

Basic Discord Bot

1const { Client, GatewayIntentBits } = require('discord.js');
2const { AIForDiscord } = require('aifordiscord-api');
3
4const client = new Client({
5  intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages, GatewayIntentBits.MessageContent]
6});
7
8const random = new AIForDiscord({
9  enableCache: true,
10  enableAI: false // Set to true if you have OpenAI API key
11});
12
13client.on('messageCreate', async (message) => {
14  if (message.author.bot || !message.content.startsWith('!')) return;
15
16  const command = message.content.slice(1).toLowerCase();
17
18  try {
19    switch (command) {
20      case 'meme':
21        const meme = await random.getMeme();
22        message.reply(meme.url);
23        break;
24
25      case 'advice':
26        const advice = await random.getAdvice();
27        message.reply(advice.advice);
28        break;
29
30      case 'neko':
31        const neko = await random.getNeko();
32        message.reply(neko.url);
33        break;
34
35      case 'joke':
36        const joke = await random.getRandomJoke();
37        const jokeText = joke.type === 'twopart' 
38          ? `${joke.setup}\n\n${joke.delivery}` 
39          : joke.joke;
40        message.reply(jokeText);
41        break;
42
43      case 'fact':
44        const fact = await random.getFact();
45        message.reply(fact.fact);
46        break;
47    }
48  } catch (error) {
49    message.reply('Something went wrong! Please try again.');
50  }
51});
52
53client.login('YOUR_BOT_TOKEN');

Advanced Bot with AI

1const { AIForDiscord } = require('aifordiscord-api');
2
3const random = new AIForDiscord({
4  openaiApiKey: process.env.OPENAI_API_KEY,
5  enableAI: true,
6  enableCache: true
7});
8
9// Custom joke generation
10const customJoke = await random.generateCustomJoke("programming");
11console.log('Custom joke:', customJoke);
12
13// Enhanced name joke
14const nameJoke = await random.getNameJoke("Alice", "Johnson");
15console.log('Name joke:', nameJoke.joke, '(Enhanced:', nameJoke.enhanced, ')');

🔧 Error Handling

The package includes comprehensive error handling:

1try {
2  const meme = await random.getMeme();
3  console.log(meme);
4} catch (error) {
5  if (error.message.includes('Rate limit exceeded')) {
6    console.log('Please wait before making another request');
7  } else if (error.message.includes('not found')) {
8    console.log('Content not available');
9  } else {
10    console.log('Network or API error:', error.message);
11  }
12}

📊 Performance Features

• Smart Caching: Reduces API calls with intelligent caching
• Rate Limiting: Prevents API abuse with configurable limits
• Error Recovery: Graceful fallbacks when AI enhancement fails
• TypeScript Support: Full type definitions for better development experience

🆚 Comparison with similar packages

Feature	aifordiscord-api	others
AI Enhancement	✅	❌
Caching System	✅	❌
Rate Limiting	✅	❌
TypeScript Support	✅	❌
Custom Joke Generation	✅	❌
Comprehensive Error Handling	✅	❌
NPM Package Info	✅	❌

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• OpenAI for AI enhancement capabilities
• Various API providers for content sources
• Discord.js community for inspiration

📞 Support

If you encounter any issues or have questions:

1. Check the examples directory
2. Review this documentation
3. Create an issue on GitHub

---

Made with ❤️ for the Discord bot community