youversion_bible 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 63a4815a0351cf4859541a8799132bd5868de1fa454eeaac6f2360b2f9cf2bfb
+  data.tar.gz: b16ce0c33cb9070c65b4f705e9974a3e54cbb801cf1b236da0e91eb349cc862f
+SHA512:
+  metadata.gz: e927115ba7982594c29a1d0b6fd01b7fb8a2cc5154ec977f8f4ff4a2705b4f9147270f0f415b06640df56f7a3ceeaaf1d008572a3e9abd5fa7ec16b393641063
+  data.tar.gz: 41d0a7f82cb0eb89219ab400ab0f370dae480e7d82092949d0332e988b93f3e7e05815b6b9ccbe23637fb65c6033ade60dfe970ad25897f0d4c811d1b9731499

data/README.md

@@ -0,0 +1,212 @@
+# Youversion Bible API - Ruby
+
+A Ruby wrapper for the YouVersion Platform Bible API built using
+**Excon**.
+
+This gem provides a Ruby client for interacting with the following
+YouVersion API resources:
+
+-   Bibles
+-   Highlights
+-   Languages
+-   Licenses
+-   Organizations
+-   Verse of the Day
+
+------------------------------------------------------------------------
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+``` ruby
+gem "youversion_bible"
+```
+
+Then execute:
+
+``` bash
+bundle install
+```
+
+------------------------------------------------------------------------
+
+## Configuration
+
+You must provide your **YouVersion Platform App Key**.
+
+``` ruby
+YouversionBible.configure do |config|
+  config.app_key = ENV["YVP_APP_KEY"]
+end
+```
+
+### Optional Configuration
+
+``` ruby
+YouversionBible.configure do |config|
+  config.app_key  = ENV["YVP_APP_KEY"]
+  config.base_url = "https://api-dev.youversion.com/v1"
+end
+```
+
+  ----------------------------------------------------------------------------
+  Setting        Default                           Description
+  -------------- --------------------------------- ---------------------------
+  app_key        ENV\["YVP_APP_KEY"\]              Your YouVersion App Key
+
+  base_url       https://api.youversion.com/v1     API base URL (prod or dev)
+  ----------------------------------------------------------------------------
+
+------------------------------------------------------------------------
+
+## Usage
+
+Create a client instance:
+
+``` ruby
+client = YouversionBible.client
+```
+
+------------------------------------------------------------------------
+
+### Bibles
+
+``` ruby
+client.bibles(language_ranges: ["en"])
+client.bible(100)
+client.bible_index(100)
+
+client.passage(
+  bible_id: 100,
+  passage_id: "JHN.3.16"
+)
+
+client.books(100)
+
+client.book(
+  bible_id: 100,
+  book_id: "GEN"
+)
+
+client.chapters(
+  bible_id: 100,
+  book_id: "GEN"
+)
+
+client.chapter(
+  bible_id: 100,
+  book_id: "GEN",
+  chapter_id: 1
+)
+
+client.verses(
+  bible_id: 100,
+  book_id: "GEN",
+  chapter_id: 1
+)
+
+client.verse(
+  bible_id: 100,
+  book_id: "GEN",
+  chapter_id: 1,
+  verse_id: 1
+)
+```
+
+------------------------------------------------------------------------
+
+### Languages
+
+``` ruby
+client.languages
+client.language("en")
+```
+
+------------------------------------------------------------------------
+
+### Organizations
+
+``` ruby
+client.organizations
+client.organization("organization_id")
+client.organization_bibles("organization_id")
+```
+
+------------------------------------------------------------------------
+
+### Verse of the Day
+
+``` ruby
+client.verse_of_the_day_calendar
+client.verse_of_the_day(32)
+```
+
+------------------------------------------------------------------------
+
+### Highlights
+
+#### (Under Construction) Documentation limited and doesn't work with normal API key
+
+``` ruby
+client.highlights(
+  bible_id: 100,
+  passage_id: "JHN.3.16"
+)
+
+client.upsert_highlight(
+  bible_id: 100,
+  passage_id: "JHN.3.16",
+  color: "44aa44"
+)
+
+client.clear_highlights(
+  bible_id: 100,
+  passage_id: "JHN.3.16"
+)
+```
+
+------------------------------------------------------------------------
+
+### Licenses
+
+#### (Under Construction) Documentation limited and doesn't work with normal API key
+
+``` ruby
+client.licenses
+```
+
+------------------------------------------------------------------------
+
+## Error Handling
+
+All API errors raise a subclass of:
+
+``` ruby
+YouversionBible::ApiError
+```
+
+Examples:
+
+``` ruby
+YouversionBible::Unauthorized
+YouversionBible::NotFound
+YouversionBible::RateLimited
+YouversionBible::ServerError
+```
+
+Handle them as needed:
+
+``` ruby
+begin
+  client.bible(999999)
+rescue YouversionBible::NotFound => e
+  puts e.message
+end
+```
+
+------------------------------------------------------------------------
+
+## License
+
+MIT

data/lib/youversion_bible/client.rb

@@ -0,0 +1,75 @@
+require "excon"
+require "json"
+
+require_relative "resources/bibles"
+require_relative "resources/highlights"
+require_relative "resources/languages"
+require_relative "resources/licenses"
+require_relative "resources/organizations"
+require_relative "resources/verse_of_the_day"
+
+module YouversionBible
+  class Client
+    def initialize(config = YouversionBible.configuration)
+      @config = config
+      validate!
+    end
+
+    # Mix in resource modules
+    include YouversionBible::Resources::Bibles
+    include YouversionBible::Resources::Highlights
+    include YouversionBible::Resources::Languages
+    include YouversionBible::Resources::Licenses
+    include YouversionBible::Resources::Organizations
+    include YouversionBible::Resources::VerseOfTheDay
+
+    private
+
+    def validate!
+      raise ConfigurationError, "YouVersion app_key is required (set config.app_key or ENV['YVP_APP_KEY'])." if @config.app_key.to_s.strip.empty?
+      raise ConfigurationError, "base_url is required" if @config.base_url.to_s.strip.empty?
+    end
+
+    def request(path:, query: nil, body: nil, headers: {}, method: :get)
+      request_headers = default_headers.merge(headers)
+      payload = body.nil? ? nil : JSON.generate(body)
+      url = @config.base_url + path
+      params = query.present? ? query : {}
+      connection = Excon.new(url, headers: request_headers, query: params.to_query, body: payload)
+      response = connection.request(method: method)
+      handle_response(response)
+    end
+
+    def default_headers
+      {
+        "X-YVP-App-Key" => @config.app_key,
+        "Accept" => "application/json",
+        "Content-Type" => "application/json"
+      }
+    end
+
+    def handle_response(response)
+      status = response.status
+      raw = response.body.to_s
+      parsed = raw.empty? ? nil : (JSON.parse(raw) rescue raw)
+
+      case status
+      when 200..299
+        parsed
+      when 400
+        raise BadRequest.new("Bad Request", status: status, body: parsed)
+      when 401
+        raise Unauthorized.new("Unauthorized (check X-YVP-App-Key)", status: status, body: parsed)
+      when 404
+        raise NotFound.new("Not Found", status: status, body: parsed)
+      when 429
+        raise RateLimited.new("Rate Limited", status: status, body: parsed)
+      when 500..599
+        raise ServerError.new("Server Error", status: status, body: parsed)
+      else
+        raise ApiError.new("Unexpected response status #{status}", status: status, body: parsed)
+      end
+    end
+  end
+end
+

data/lib/youversion_bible/configuration.rb

@@ -0,0 +1,13 @@
+module YouversionBible
+  class Configuration
+    DEFAULT_BASE_URL = "https://api.youversion.com/v1"
+
+    attr_accessor :app_key, :base_url
+
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @app_key = ENV["YVP_APP_KEY"]
+    end
+  end
+end
+

data/lib/youversion_bible/errors.rb

@@ -0,0 +1,21 @@
+module YouversionBible
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status:, body:)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+
+  class Unauthorized < ApiError; end
+  class NotFound < ApiError; end
+  class RateLimited < ApiError; end
+  class ServerError < ApiError; end
+  class BadRequest < ApiError; end
+end
+

data/lib/youversion_bible/railtie.rb

@@ -0,0 +1,11 @@
+require "rails/railtie"
+
+module YouversionBible
+  class Railtie < Rails::Railtie
+    initializer "youversion_bible.configure" do
+      YouversionBible.configure do |config|
+        config.app_key ||= ENV["YVP_APP_KEY"]
+      end
+    end
+  end
+end

data/lib/youversion_bible/resources/bibles.rb

@@ -0,0 +1,76 @@
+module YouversionBible
+  module Resources
+    module Bibles
+      # GET /bibles
+      def bibles(language_ranges: ["en"], all_available: true, page_size: 100, fields: nil, page_token: nil, license_id: nil)
+        query = {
+          language_ranges: Array(language_ranges), # encoded as language_ranges[]
+          all_available: all_available,
+          page_size: page_size,
+          fields: fields, # fields[]
+          page_token: page_token
+        }
+        query.merge!({license_id: license_id}) if license_id.present?
+        request(
+          path: "/bibles",
+          query: query
+        )
+      end
+
+      # GET /bibles/{bible_id}
+      def bible(bible_id)
+        request(path: "/bibles/#{bible_id}")
+      end
+
+      # GET /bibles/{bible_id}/index
+      def bible_index(bible_id)
+        request(path: "/bibles/#{bible_id}/index")
+      end
+
+      # GET /bibles/{bible_id}/passages/{passage_id}
+      # passage_id examples: "JHN.3.16", "GEN.1", "MAT.1.1-5" (per docs usage)
+      def passage(bible_id:, passage_id:)
+        request(path: "/bibles/#{bible_id}/passages/#{escape_path(passage_id)}")
+      end
+
+      # GET /bibles/{bible_id}/books
+      def books(bible_id)
+        request(path: "/bibles/#{bible_id}/books")
+      end
+
+      # GET /bibles/{bible_id}/books/{book_id}
+      # book_id example: "JHN", "GEN" (USFM)
+      def book(bible_id:, book_id:)
+        request(path: "/bibles/#{bible_id}/books/#{escape_path(book_id)}")
+      end
+
+      # GET /bibles/{bible_id}/books/{book_id}/chapters
+      def chapters(bible_id:, book_id:)
+        request(path: "/bibles/#{bible_id}/books/#{escape_path(book_id)}/chapters")
+      end
+
+      # GET /bibles/{bible_id}/books/{book_id}/chapters/{chapter_id}
+      def chapter(bible_id:, book_id:, chapter_id:)
+        request(path: "/bibles/#{bible_id}/books/#{escape_path(book_id)}/chapters/#{chapter_id}")
+      end
+
+      # GET /bibles/{bible_id}/books/{book_id}/chapters/{chapter_id}/verses
+      def verses(bible_id:, book_id:, chapter_id:)
+        request(path: "/bibles/#{bible_id}/books/#{escape_path(book_id)}/chapters/#{chapter_id}/verses")
+      end
+
+      # GET /bibles/{bible_id}/books/{book_id}/chapters/{chapter_id}/verses/{verse_id}
+      def verse(bible_id:, book_id:, chapter_id:, verse_id:)
+        request(path: "/bibles/#{bible_id}/books/#{escape_path(book_id)}/chapters/#{chapter_id}/verses/#{verse_id}")
+      end
+
+      private
+
+      def escape_path(str)
+        # Basic safe escaping for path segments (spaces, etc.)
+        CGI.escape(str.to_s).gsub("+", "%20")
+      end
+    end
+  end
+end
+

data/lib/youversion_bible/resources/highlights.rb

@@ -0,0 +1,42 @@
+module YouversionBible
+  module Resources
+    module Highlights
+      # TODO not sure how these are supposed to work
+      # it looks like per user as we get an API key error but docs are not clear
+
+      # GET /highlights?bible_id=...&passage_id=...
+      def highlights(bible_id:, passage_id:)
+        request(
+          path: "/highlights",
+          query: { bible_id: bible_id, passage_id: passage_id }
+        )
+      end
+
+      # POST /highlights  { bible_id, passage_id, color }
+      # color must be 6-char hex like "44aa44"
+      def upsert_highlight(bible_id:, passage_id:, color:)
+        request(
+          method: :post,
+          path: "/highlights",
+          body: { bible_id: bible_id, passage_id: passage_id, color: color }
+        )
+      end
+
+      # DELETE /highlights/{passage_id_path}?bible_id=...
+      def clear_highlights(bible_id:, passage_id:)
+        request(
+          method: :delete,
+          path: "/highlights/#{escape_path(passage_id)}",
+          query: { bible_id: bible_id }
+        )
+      end
+
+      private
+
+      def escape_path(str)
+        CGI.escape(str.to_s).gsub("+", "%20")
+      end
+    end
+  end
+end
+

data/lib/youversion_bible/resources/languages.rb

@@ -0,0 +1,26 @@
+module YouversionBible
+  module Resources
+    module Languages
+      # GET /languages
+      def languages(page_size: 100, fields: nil, page_token: nil, country: nil)
+        request(
+          path: "/languages",
+          query: { page_size: page_size, fields: fields, page_token: page_token, country: country }
+        )
+      end
+
+      # GET /languages/{language_id}
+      # language_id example: "en" or "sr-Latn"
+      def language(language_id)
+        request(path: "/languages/#{escape_path(language_id)}")
+      end
+
+      private
+
+      def escape_path(str)
+        CGI.escape(str.to_s).gsub("+", "%20")
+      end
+    end
+  end
+end
+

data/lib/youversion_bible/resources/licenses.rb

@@ -0,0 +1,16 @@
+module YouversionBible
+  module Resources
+    module Licenses
+      # GET /licenses
+      # Supports bible_id, developer_id, all_available per docs.
+      def licenses(bible_id: nil, all_available: true, developer_id: nil)
+        # TODO this one doesn't seem to work with the normal API key, figure out why
+        request(
+          path: "/licenses",
+          query: { all_available: all_available, bible_id: bible_id, developer_id: developer_id }
+        )
+      end
+    end
+  end
+end
+

data/lib/youversion_bible/resources/organizations.rb

@@ -0,0 +1,41 @@
+module YouversionBible
+  module Resources
+    module Organizations
+      # GET /organizations
+      def organizations(bible_id, accept_language: "en")
+        request(
+          path: "/organizations",
+          query: { bible_id: bible_id },
+          headers: { "Accept-Language" => accept_language }
+        )
+      end
+
+      # GET /organizations/{organization_id}
+      def organization(organization_id, accept_language: "en")
+        request(
+          path: "/organizations/#{escape_path(organization_id)}",
+          headers: { "Accept-Language" => accept_language }
+        )
+      end
+
+      # GET /organizations/{organization_id}/bibles
+      def organization_bibles(organization_id, page_size: 100, fields: nil, page_token: nil)
+        query = {fields: fields, page_token: page_token }
+        if fields.present? && fields.count <= 3
+          query.merge!({page_size: page_size}) if page_size.present?
+        end
+        request(
+          path: "/organizations/#{escape_path(organization_id)}/bibles",
+          query: query
+        )
+      end
+
+      private
+
+      def escape_path(str)
+        CGI.escape(str.to_s).gsub("+", "%20")
+      end
+    end
+  end
+end
+

data/lib/youversion_bible/resources/verse_of_the_day.rb

@@ -0,0 +1,17 @@
+module YouversionBible
+  module Resources
+    module VerseOfTheDay
+      # GET /verse_of_the_days
+      def verse_of_the_day_calendar
+        request(path: "/verse_of_the_days")
+      end
+
+      # GET /verse_of_the_days/{day}
+      # day: 1..365 (or 366)
+      def verse_of_the_day(day)
+        request(path: "/verse_of_the_days/#{day}")
+      end
+    end
+  end
+end
+

data/lib/youversion_bible/version.rb

@@ -0,0 +1,4 @@
+module YouversionBible
+  VERSION = "0.1.0"
+end
+

data/lib/youversion_bible.rb

@@ -0,0 +1,30 @@
+require "youversion_bible/version"
+require "youversion_bible/configuration"
+require "youversion_bible/errors"
+require "youversion_bible/client"
+
+require "youversion_bible/resources/bibles"
+require "youversion_bible/resources/highlights"
+require "youversion_bible/resources/languages"
+require "youversion_bible/resources/licenses"
+require "youversion_bible/resources/organizations"
+require "youversion_bible/resources/verse_of_the_day"
+
+require "youversion_bible/railtie" if defined?(Rails)
+
+module YouversionBible
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def client
+      Client.new(configuration)
+    end
+  end
+end
+

data/youversion_bible.gemspec

@@ -0,0 +1,32 @@
+require_relative "lib/youversion_bible/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "youversion_bible"
+  spec.version       = YouversionBible::VERSION
+  spec.authors       = ["JD Warren"]
+  spec.email         = ["johndavid400@gmail.com"]
+
+  spec.summary       = "Ruby wrapper for the YouVersion Bible API"
+  spec.description   = "A Ruby gem wrapper around the YouVersion Bible API. Includes: Bibles, Highlights, Languages, Licenses, Organizations, and Verse of the Day endpoints."
+  spec.homepage      = "https://github.com/johndavid400/youversion_bible"
+  spec.license       = "MIT"
+
+  spec.required_ruby_version = ">= 3.0"
+
+  # Files included in the gem
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0")
+  end
+
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "excon", "~> 0.109"
+  spec.add_dependency "json", ">= 2.0"
+
+  # Dev dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "standard", "~> 1.35"
+  spec.add_development_dependency "pry", "~> 0.14"
+end

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: youversion_bible
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- JD Warren
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: excon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.109'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.109'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.35'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+description: 'A Ruby gem wrapper around the YouVersion Bible API. Includes: Bibles,
+  Highlights, Languages, Licenses, Organizations, and Verse of the Day endpoints.'
+email:
+- johndavid400@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/youversion_bible.rb
+- lib/youversion_bible/client.rb
+- lib/youversion_bible/configuration.rb
+- lib/youversion_bible/errors.rb
+- lib/youversion_bible/railtie.rb
+- lib/youversion_bible/resources/bibles.rb
+- lib/youversion_bible/resources/highlights.rb
+- lib/youversion_bible/resources/languages.rb
+- lib/youversion_bible/resources/licenses.rb
+- lib/youversion_bible/resources/organizations.rb
+- lib/youversion_bible/resources/verse_of_the_day.rb
+- lib/youversion_bible/version.rb
+- youversion_bible.gemspec
+homepage: https://github.com/johndavid400/youversion_bible
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby wrapper for the YouVersion Bible API
+test_files: []