YouVersion SDK

A production-ready, open-source Dart/Flutter SDK for the YouVersion REST API. This package provides a clean and idiomatic way to fetch Bibles, Books, Chapters, and Verses in Dart and Flutter applications.

Features

  • Fetch Bibles: List all available Bible versions and translations.
  • List Books: Retrieve the list of books available within a specific Bible version.
  • Retrieve Passages: Fetch specific scripture passages (e.g., John 3:16) with reference and content details.
  • Clear Error Handling: Handle API-specific errors, authentication failures, rate limits, and network issues gracefully.

Getting started

You'll need a developer token from the YouVersion Developer Portal (or register on the YouVersion Platform) to use this SDK.

Installation

Add youversion_sdk to your project by running:

flutter pub add youversion_sdk

(For Dart-only projects, run dart pub add youversion_sdk instead)

Setup

Ensure you have network permissions enabled in your target platforms (Android, iOS, macOS).

Usage

import 'package:youversion_sdk/youversion_sdk.dart';

void main() async {
  // 1. Initialize the client
  final client = YouVersionClient(
    developerToken: 'YOUR_DEVELOPER_TOKEN',
    language: 'en',
  );

  // 2. Fetch data via repositories
  try {
    final bibles = await client.bibles.list();
    
    for (final bible in bibles) {
      print('Bible: ${bible.title} (${bible.abbreviation})');
    }
  } on YouVersionException catch (e) {
    // 3. Exhaustive error handling via sealed classes
    switch (e) {
      case YouVersionAuthException():
        print('Check your developer token!');
      case YouVersionRateLimitException():
        print('Too many requests. Slow down.');
      case YouVersionNetworkException():
        print('No internet connection.');
      case YouVersionNotFoundException():
      case YouVersionUnknownException():
        print('An error occurred: ${e.message}');
    }
  }
}

Future Plans

  • User Authentication: Support authenticating users directly with YouVersion to perform user-specific operations (e.g., fetching highlights, bookmarks, or reading progress).

Additional information

Contributions, bug reports, and feature requests are welcome via the repository's issue tracker.

Libraries

youversion_sdk