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

npm install aifordiscord-api

🚀 Quick Start

const { AIForDiscord } = require('aifordiscord-api');

// Basic usage (no AI features)
const random = new AIForDiscord();

// With AI enhancement (requires OpenAI API key)
const random = new AIForDiscord({
  openaiApiKey: 'your-openai-key',
  enableAI: true,
  enableCache: true
});

// Get a meme
const meme = await random.getMeme();
console.log(meme.title, meme.url);

// Get advice
const advice = await random.getAdvice();
console.log(advice.advice);

📚 API Reference

Basic Content Methods

`getMeme()`

Returns a random meme from Reddit with metadata.

const data = await random.getMeme();
message.channel.send({
  embeds: [{
    title: data.title,
    image: { url: data.url },
    url: data.postLink,
    footer: { text: `r/${data.subreddit} • ${data.ups} upvotes` }
  }]
});

Returns: MemeResponse

{
  title: string;
  url: string;
  postLink: string;
  subreddit: string;
  author: string;
  nsfw: boolean;
  spoiler: boolean;
  ups: number;
}

`getAdvice()`

Provides random advice with optional AI enhancement.

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

Returns: AdviceResponse

{
  advice: string;
  slip_id: number;
}

`getNeko()`

Provides a random neko (cat girl) image.

const data = await random.getNeko();
message.channel.send({
  embeds: [{
    title: '🐱 Random Neko',
    image: { url: data.url }
  }]
});

Returns: NekoResponse

{
  url: string;
}

`getRandomJoke()`

Provides a random funny joke with optional AI enhancement.

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

Returns: JokeResponse

{
  setup?: string;
  delivery?: string;
  joke?: string;
  category: string;
  type: string;
  safe: boolean;
  id: number;
}

`getNameJoke(firstName, lastName?)`

Provides a random funny joke related to the given name.

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

Parameters:

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

Returns: NameJokeResponse

{
  joke: string;
  name: string;
  enhanced: boolean;
}

`getAnimeImgURL(type)`

Provides a random anime image URL based on action type.

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

Parameters:

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

Returns: AnimeImageResponse

{
  url: string;
  type: string;
}

`getFact()`

Provides a random fact with optional AI enhancement.

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

Returns: FactResponse

{
  fact: string;
  source?: string;
  enhanced: boolean;
}

`getNPM(packageName)`

Provides information about an NPM package.

const data = await random.getNPM("discord.js");
message.channel.send({
  embeds: [{
    title: `📦 ${data.name}`,
    description: data.description,
    fields: [
      { name: 'Version', value: data.version, inline: true },
      { name: 'Author', value: data.author || 'Unknown', inline: true }
    ]
  }]
});

`getQuote()`

Provides a random inspirational quote.

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

`getDogImage()`

Provides a random dog image.

const data = await random.getDogImage();
message.channel.send({
  embeds: [{
    title: '🐕 Random Dog',
    image: { url: data.url }
  }]
});

`getCatImage()`

Provides a random cat image.

const data = await random.getCatImage();
message.channel.send({
  embeds: [{
    title: '🐱 Random Cat',
    image: { url: data.url }
  }]
});

`getTrivia(category?, difficulty?)`

Provides a trivia question with multiple choice answers.

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

`getDadJoke()`

Provides a random dad joke.

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

`getChuckNorrisJoke()`

Provides a random Chuck Norris joke.

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

`getCompliment()`

Provides a random compliment.

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

`getAffirmation()`

Provides a positive affirmation.

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

`getGitHubUser(username)`

Provides information about a GitHub user.

const data = await random.getGitHubUser("octocat");
message.channel.send({
  embeds: [{
    title: `👨‍💻 ${data.name || data.username}`,
    description: data.bio,
    thumbnail: { url: data.avatarUrl },
    fields: [
      { name: 'Followers', value: data.followers.toString(), inline: true },
      { name: 'Following', value: data.following.toString(), inline: true },
      { name: 'Public Repos', value: data.publicRepos.toString(), inline: true }
    ],
    url: data.htmlUrl
  }]
});

AI-Enhanced Methods

`generateCustomJoke(topic)` 🤖

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

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

Parameters:

topic (string): Topic for the joke

Returns: string - AI-generated joke

Utility Methods

`clearCache()`

Clears the internal cache.

random.clearCache();

`getConfig()`

Returns current configuration.

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

`isAIEnabled()`

Checks if AI features are enabled and available.

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

⚙️ Configuration Options

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

🤖 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

const { Client, GatewayIntentBits } = require('discord.js');
const { AIForDiscord } = require('aifordiscord-api');

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

const random = new AIForDiscord({
  enableCache: true,
  enableAI: false // Set to true if you have OpenAI API key
});

client.on('messageCreate', async (message) => {
  if (message.author.bot || !message.content.startsWith('!')) return;

  const command = message.content.slice(1).toLowerCase();

  try {
    switch (command) {
      case 'meme':
        const meme = await random.getMeme();
        message.reply(meme.url);
        break;

      case 'advice':
        const advice = await random.getAdvice();
        message.reply(advice.advice);
        break;

      case 'neko':
        const neko = await random.getNeko();
        message.reply(neko.url);
        break;

      case 'joke':
        const joke = await random.getRandomJoke();
        const jokeText = joke.type === 'twopart' 
          ? `${joke.setup}\n\n${joke.delivery}` 
          : joke.joke;
        message.reply(jokeText);
        break;

      case 'fact':
        const fact = await random.getFact();
        message.reply(fact.fact);
        break;
    }
  } catch (error) {
    message.reply('Something went wrong! Please try again.');
  }
});

client.login('YOUR_BOT_TOKEN');

Advanced Bot with AI

const { AIForDiscord } = require('aifordiscord-api');

const random = new AIForDiscord({
  openaiApiKey: process.env.OPENAI_API_KEY,
  enableAI: true,
  enableCache: true
});

// Custom joke generation
const customJoke = await random.generateCustomJoke("programming");
console.log('Custom joke:', customJoke);

// Enhanced name joke
const nameJoke = await random.getNameJoke("Alice", "Johnson");
console.log('Name joke:', nameJoke.joke, '(Enhanced:', nameJoke.enhanced, ')');

🔧 Error Handling

The package includes comprehensive error handling:

try {
  const meme = await random.getMeme();
  console.log(meme);
} catch (error) {
  if (error.message.includes('Rate limit exceeded')) {
    console.log('Please wait before making another request');
  } else if (error.message.includes('not found')) {
    console.log('Content not available');
  } else {
    console.log('Network or API error:', error.message);
  }
}

📊 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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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:

Check the examples directory
Review this documentation
Create an issue on GitHub

Made with ❤️ for the Discord bot community