gospel_catholic

An NPM package to fetch daily Catholic gospel readings from Vatican News with translation support. Useful for WhatsApp bots, Discord bots, Telegram bots, and more.

Installation

npm install gospel_catholic

Features

✨ New in v1.1.0+

• ⚡ Automatic Caching - Cache gospel per day to reduce API calls
• 🔄 Retry Logic - Exponential backoff for failed requests
• 🌍 Language Validation - Support for 100+ languages
• 📦 Batch Translation - Get gospel in multiple languages at once
• 🎨 Output Formatting - Support for plain, markdown, HTML, and JSON formats
• 🐛 Debug Mode - Enable detailed logging for troubleshooting
• ⏱️ Configurable Timeout - Custom request timeout settings
• 🧹 Cache Management - Clear cache when needed

Usage

Basic Usage (English)

const GospelCatholic = require('gospel_catholic');

// Create a new instance with default settings (English)
const gospel = new GospelCatholic();

// Get today's gospel
const result = await gospel.getGospel();
console.log('Gospel Title:', result.original.title);
console.log('Text:', result.original.text);

With Translation

// Create a new instance with Spanish translation
const gospel = new GospelCatholic({ language: 'es' });

const result = await gospel.getGospel();
console.log('Original Title:', result.original.title);
console.log('Translated Title:', result.translated.title);
console.log('Translated Text:', result.translated.text);

Advanced Configuration

const gospel = new GospelCatholic({
  language: 'es',        // Target language
  cache: true,           // Enable caching (default: true)
  timeout: 15000,        // Request timeout in ms (default: 10000)
  debug: true            // Enable debug logging (default: false)
});

const result = await gospel.getGospel();

Get Gospel in Multiple Languages

const gospel = new GospelCatholic();

const results = await gospel.getGospelInMultipleLanguages(['en', 'es', 'fr', 'si']);
results.forEach(gospel => {
  console.log(`${gospel.language}:`, gospel.translated?.title || gospel.original.title);
});

Format Output

const gospel = new GospelCatholic({ language: 'es' });
const result = await gospel.getGospel();

// Different format options
console.log(gospel.formatOutput(result, 'plain'));     // Plain text (default)
console.log(gospel.formatOutput(result, 'markdown'));  // Markdown
console.log(gospel.formatOutput(result, 'html'));      // HTML
console.log(gospel.formatOutput(result, 'json'));      // JSON

Validate Language Support

const gospel = new GospelCatholic();

if (gospel.isValidLanguage('es')) {
  console.log('Spanish is supported');
}

// List all supported languages
console.log(GospelCatholic.SUPPORTED_LANGUAGES);

Cache Management

const gospel = new GospelCatholic();

// First call - fetches from API
let result = await gospel.getGospel();

// Second call (same day) - returns cached result
result = await gospel.getGospel();

// Clear cache if needed
gospel.clearCache();

// Next call - fetches fresh data
result = await gospel.getGospel();

Debug Mode

const gospel = new GospelCatholic({ debug: true });

const result = await gospel.getGospel();
// Output:
// [GospelCatholic] Fetching gospel for es
// [GospelCatholic] Fetching URL (attempt 1/3)
// [GospelCatholic] Translating to es
// [GospelCatholic] Gospel data cached

Supported Languages

The package supports all languages available in Google Translate, including:

• en - English (default)
• es - Spanish
• fr - French
• it - Italian
• de - German
• pt - Portuguese
• ru - Russian
• zh - Chinese
• ja - Japanese
• ko - Korean
• ar - Arabic
• hi - Hindi
• bn - Bengali
• si - Sinhala (supported with Google Translate)
• And many more ISO language codes (100+ languages)

The package uses Google Translate's API which supports over 100 languages including those with less common support like Sinhala, Amharic, Kurdish, etc.

Integration Examples

WhatsApp Bot (using whatsapp-web.js)

const { Client } = require('whatsapp-web.js');
const GospelCatholic = require('gospel_catholic');
const client = new Client();

client.on('message', async msg => {
  if (msg.body === '!gospel') {
    const gospel = new GospelCatholic({ debug: true });
    const result = await gospel.getGospel();
    const formatted = gospel.formatOutput(result, 'plain');
    msg.reply(formatted);
  }
  
  if (msg.body.startsWith('!gospel_')) {
    const lang = msg.body.split('_')[1];
    const gospel = new GospelCatholic({ language: lang });
    const result = await gospel.getGospel();
    msg.reply(gospel.formatOutput(result, 'plain'));
  }
});

client.initialize();

Discord Bot (using discord.js)

const { Client, GatewayIntentBits } = require('discord.js');
const GospelCatholic = require('gospel_catholic');
const client = new Client({ intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMessages] });

client.on('messageCreate', async message => {
  if (message.content === '!gospel') {
    const gospel = new GospelCatholic();
    const result = await gospel.getGospel();
    const formatted = gospel.formatOutput(result, 'markdown');
    message.channel.send('```\n' + formatted + '\n```');
  }
  
  if (message.content === '!gospel_multi') {
    const gospel = new GospelCatholic();
    const results = await gospel.getGospelInMultipleLanguages(['en', 'es', 'fr']);
    const formatted = results.map(g => gospel.formatOutput(g, 'markdown')).join('\n\n---\n\n');
    message.channel.send('```\n' + formatted + '\n```');
  }
});

client.login('YOUR_DISCORD_BOT_TOKEN');

Telegram Bot (using node-telegram-bot-api)

const TelegramBot = require('node-telegram-bot-api');
const GospelCatholic = require('gospel_catholic');

const bot = new TelegramBot('YOUR_TELEGRAM_BOT_TOKEN', { polling: true });

bot.onText(/\/gospel/, async (msg) => {
  const chatId = msg.chat.id;
  const gospel = new GospelCatholic();
  const result = await gospel.getGospel();
  const formatted = gospel.formatOutput(result, 'markdown');
  bot.sendMessage(chatId, formatted, { parse_mode: 'Markdown' });
});

bot.onText(/\/gospel_([a-z]{2})/, async (msg, match) => {
  const chatId = msg.chat.id;
  const language = match[1];
  
  const gospel = new GospelCatholic({ language });
  const result = await gospel.getGospel();
  const formatted = gospel.formatOutput(result, 'markdown');
  bot.sendMessage(chatId, formatted, { parse_mode: 'Markdown' });
});

API Reference

Constructor Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | language | string | 'en' | Target language code for translation | | cache | boolean | true | Enable automatic daily caching | | timeout | number | 10000 | Request timeout in milliseconds | | debug | boolean | false | Enable debug logging |

Methods

getGospel(date?): Promise<Object>

Fetch the gospel of the day with automatic caching and translation.

getGospelInMultipleLanguages(languages): Promise<Object[]>

Fetch gospel in multiple languages at once.

formatOutput(gospel, format): string

Format the gospel output (plain, markdown, html, json).

isValidLanguage(lang): boolean

Check if a language code is supported.

clearCache(): void

Clear the cached gospel data.

translate(text, targetLang): Promise<string>

Translate text to a target language.

License

MIT