AdventoAPI.CPB 1.0.5

AdventoAPI.CPB

A .NET 10 library for fetching and parsing Bible lessons and devotionals from the CPB (Centro de Pesquisa Bíblica) website.

Overview

AdventoAPI.CPB provides a simple and efficient way to retrieve:

• Adult Bible Lessons (LicaoAdulto) - Quarterly lesson materials with daily content, audio, and supplementary materials
• Devotionals (DevocionalBase) - Daily devotional content for different audiences:
  • DevocionalDiario - Daily devotionals
  • DevocionalJovem - Youth devotionals
  • DevocionalMulher - Women's devotionals

The library handles HTML parsing, data extraction, and provides async-friendly APIs with built-in throttling support.

Features

• 📚 Multiple Content Types: Access Bible lessons and devotionals
• 🔄 Async/Await Support: Fully asynchronous APIs with CancellationToken support
• ⚡ Throttling: Built-in concurrency control using SemaphoreSlim
• 🔗 Rich Data Models: Type-safe DTOs for all content
• 🌐 HTML Parsing: Leverages AngleSharp for reliable content extraction
• 📅 Flexible Filtering: Search devotionals by keywords, week, or date range
• 🎵 Media Support: Access to audio files and YouTube links

Installation

Add the NuGet package reference to your project:

dotnet add package AdventoAPI.CPB

Or manually add to your .csproj:

<PackageReference Include="AdventoAPI.CPB" Version="1.0.4" />

Quick Start

Bible Lessons (Adult)

using AdventoAPI.CPB.API;

// Create a client instance
var licaoAdulto = new LicaoAdulto();

// Get the current quarterly lessons
var trimestre = await licaoAdulto.GetLicoesAsync();
Console.WriteLine($"Quarter {trimestre.Trimestre} - Year {trimestre.Ano}");

// Get a specific lesson for the week
var licaoSemana = await licaoAdulto.GetLicaoAsync(trimestre.CurrentSemana);

// Get all lessons for the quarter
var todasAsLicoes = await licaoAdulto.GetAllLicoesTrimestreAsync();

// Get all audio lessons with concurrency control (max 3 concurrent requests)
var audios = await licaoAdulto.GetAllLicoesSemanaAudiosTrimestreThrottledAsync(maxConcurrency: 3);

Devotionals

// Create a devotional instance
var devocionalDiario = new DevocionalDiario();

// Get all weekly blocks of devotionals
var semanas = await devocionalDiario.GetDevocionaisAsync();

// Get meditation information
var meditacoes = await devocionalDiario.GetMeditacaoInfoAsync();

// Get a specific day's devotional
var devotionalDia = await devocionalDiario.GetDevocionalDia(new Uri("https://..."));

// Search devotionals by keyword
var resultados = await devocionalDiario.BuscarPalavraChaveDevocionais("fé");

// Search within a specific week
var resultadosSemana = await devocionalDiario.BuscarPalavrasChaveSemana(0, new[] { "amor", "graça" });

// Search by date range
var dataInicio = new DevocionalDayMonth(1, 1);
var dataFim = new DevocionalDayMonth(31, 12);
var resultadosPeriodo = await devocionalDiario.BuscarPalavrasChaveDataRange(dataInicio, dataFim, "esperança");

API Reference

LicaoAdulto

Main API for accessing adult Bible lessons.

Methods

DevocionalBase

Abstract base class for devotional content. Inherited by:

• DevocionalDiario
• DevocionalJovem
• DevocionalMulher

Methods

Data Models

Key DTOs

LicaoSemanaData - A week's complete lesson content

public class LicaoSemanaData
{
    public LicaoSabado? Sabado { get; init; }        // Saturday lesson
    public LicaoDia? Domingo { get; init; }          // Daily lessons (Sunday-Friday)
    public LicaoDia? Segunda { get; init; }
    public LicaoDia? Terca { get; init; }
    public LicaoDia? Quarta { get; init; }
    public LicaoDia? Quinta { get; init; }
    public LicaoDia? Sexta { get; init; }
    public LicaoAuxiliar? Auxiliar { get; init; }    // Supplementary material
    public LicaoInformativo? Informativo { get; set; }
    public LicaoComentario? Comentario { get; init; }
}

DevocionalInfo - A specific devotional entry

public record DevocionalInfo(
    Uri Url,
    string DiadaSemanaNome,
    string DiaMesNome,
    string Title,
    string Content,
    string VersoBiblico
);

Configuration

Custom HTTP Client

Pass your own HttpClient for custom configuration:

var httpClient = new HttpClient(new SocketsHttpHandler
{
    PooledConnectionIdleTimeout = TimeSpan.FromMinutes(2),
    PooledConnectionLifetime = TimeSpan.FromMinutes(15)
});

var licaoAdulto = new LicaoAdulto(httpClient);

Custom Selectors

Customize HTML selectors if the website structure changes:

var customOptions = new LicaoAdultoOptions
{
    Selectors = new LicaoAdultoOptions.SelectorsOptions
    {
        CardsContainer = ".custom-container",
        // ... other selectors
    }
};

var licaoAdulto = new LicaoAdulto(options: customOptions);

Cancellation Token Support

All methods support cancellation tokens for better control over async operations:

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
var licoes = await licaoAdulto.GetLicoesAsync(cts.Token);

Error Handling

The library throws standard .NET exceptions:

try
{
    var licao = await licaoAdulto.GetLicaoAsync(new Uri("https://invalid.url"));
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
}
catch (FormatException ex)
{
    Console.WriteLine($"Parsing error: {ex.Message}");
}

Requirements

• .NET 10+
• AngleSharp 1.4.0+ - For HTML parsing

Performance Tips

1. Reuse HttpClient: Use a single HttpClient instance across your application
2. Use Throttling: For batch operations, use the throttled methods to avoid overwhelming the server:

   await licaoAdulto.GetAllLicoesTrimestreThrottledAsync(maxConcurrency: 3);

3. Cache Results: Store frequently accessed data locally

Contributing

Contributions are welcome! Please submit pull requests to the GitHub repository.

License

This project is licensed under the terms specified in LICENSE.md.

Repository

GenAI.CSharp on GitHub

Author

MauryDev

Support

For issues, questions, or suggestions, please visit the GitHub Issues page.