widebible 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f41d0970273a19e1e291ea26f15b158f12883e7e77343c3586d6dd3b841d90d5
+  data.tar.gz: 485fb9bacde4dc583d6ccb6a2666e8adc48cd204fbd91a185c5b754448f1c92f
+SHA512:
+  metadata.gz: 9e8528b7bf01b2cd96bed8f2803f60708d7b7665d71acaba40ffce88ebd71dae0d5aff5f078d59b8852433808811d292ef48bd4afbdcfa05959c6adc07228f6b
+  data.tar.gz: 6626176329206faf26faa2d33fd7dff9baf7be73139044b0009619fcc235d3ae205ddd160a1ae45e3ccfd6ea25b8e2abed930edcaacbb56659d69d4db7f3fbf9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WideHoly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,251 @@
+# widebible
+
+[![Gem Version](https://badge.fury.io/rb/widebible.svg)](https://rubygems.org/gems/widebible)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.0-red)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://rubygems.org/gems/widebible)
+
+Ruby client for the [WideBible](https://widebible.com) API. Access all 66 books of the Bible, 31,102 verses across 4 translations (KJV, ASV, BBE, YLT), biblical people, places, topics, cross-references, glossary with Hebrew and Greek terms, timeline events, and reading plans. Zero runtime dependencies -- uses only Ruby stdlib (`net/http`, `json`, `uri`).
+
+WideBible is a comprehensive Bible encyclopedia and scripture platform providing structured verse data, cross-references between passages, biographical profiles of biblical figures, geocoded holy sites, and thematic verse collections -- all accessible through a free REST API.
+
+> **Explore the Bible at [widebible.com](https://widebible.com)** -- [Books](https://widebible.com/books/), [People](https://widebible.com/people/), [Places](https://widebible.com/places/), [Topics](https://widebible.com/topics/) , [Timeline](https://widebible.com/timeline/)
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [What You Can Do](#what-you-can-do)
+  - [Browse Bible Books](#browse-bible-books)
+  - [Look Up Verses](#look-up-verses)
+  - [Search Scripture](#search-scripture)
+  - [Explore Biblical People](#explore-biblical-people)
+  - [Discover Holy Places](#discover-holy-places)
+  - [Follow Cross-References](#follow-cross-references)
+  - [Study Glossary Terms](#study-glossary-terms)
+  - [Walk the Timeline](#walk-the-timeline)
+  - [Follow Reading Plans](#follow-reading-plans)
+- [API Reference](#api-reference)
+- [Learn More About the Bible](#learn-more-about-the-bible)
+- [WideHoly Scripture Family](#wideholy-scripture-family)
+- [Also Available](#also-available)
+- [License](#license)
+
+## Install
+
+```bash
+gem install widebible
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "widebible"
+```
+
+## Quick Start
+
+```ruby
+require "widebible"
+
+# Create a client (zero configuration needed)
+client = WideBible::Client.new
+
+# List all 66 books of the Bible
+books = client.list_books
+puts books["results"].first["name"]  # => "Genesis"
+
+# Get a specific verse -- John 3:16 in the KJV
+verse = client.get_verse("john", 3, 16)
+puts verse["results"].first["text"]
+
+# Search across all scripture
+results = client.search("In the beginning")
+results["results"].each { |v| puts v["reference"] }
+```
+
+## What You Can Do
+
+### Browse Bible Books
+
+The Bible contains 66 books divided into the Old Testament (39 books) and New Testament (27 books). Books are organized into groups: Pentateuch, Historical Books, Wisdom Literature, Major Prophets, Minor Prophets, Gospels, Pauline Epistles, General Epistles, and Revelation.
+
+```ruby
+# List all books of the Bible
+books = client.list_books
+
+# Get details for a specific book
+genesis = client.get_book("genesis")
+puts genesis["name"]           # => "Genesis"
+puts genesis["chapter_count"]  # => 50
+
+# Browse book groups (Pentateuch, Gospels, etc.)
+groups = client.list_book_groups
+```
+
+### Look Up Verses
+
+WideBible provides 31,102 verses across 4 English translations. Each verse includes the original text, reference notation, and chapter/book context. The KJV (King James Version, 1611) is the default translation.
+
+| Translation | Code | Year | Style |
+|-------------|------|------|-------|
+| King James Version | `kjv` | 1611 | Formal equivalence |
+| American Standard Version | `asv` | 1901 | Literal |
+| Bible in Basic English | `bbe` | 1965 | Simplified vocabulary |
+| Young's Literal Translation | `ylt` | 1862 | Ultra-literal |
+
+```ruby
+# Get John 3:16 in KJV (default)
+verse = client.get_verse("john", 3, 16)
+
+# Get Genesis 1:1 in ASV translation
+verse = client.get_verse("genesis", 1, 1, translation: "asv")
+
+# List chapters in a book
+chapters = client.list_chapters(book: "psalms")
+```
+
+### Search Scripture
+
+Full-text search across all Bible verses with relevance ranking.
+
+```ruby
+# Search for verses about love
+results = client.search("love", limit: 10)
+results["results"].each do |verse|
+  puts "#{verse["reference"]}: #{verse["text"]}"
+end
+
+# Search for creation passages
+results = client.search("In the beginning God created")
+```
+
+### Explore Biblical People
+
+Biographical profiles of prophets, kings, apostles, and other key figures mentioned in the Bible, with their roles, relationships, and associated scripture references.
+
+```ruby
+# List all biblical people
+people = client.list_people
+
+# Get details for a specific person
+moses = client.get_person("moses")
+puts moses["name"]        # => "Moses"
+puts moses["description"] # Biography and significance
+```
+
+### Discover Holy Places
+
+Geocoded biblical locations with historical context, archaeological notes, and scripture references. From the Garden of Eden to first-century Jerusalem.
+
+```ruby
+# List biblical places
+places = client.list_places
+
+# Get details for a specific place
+jerusalem = client.get_place("jerusalem")
+puts jerusalem["name"]
+```
+
+### Follow Cross-References
+
+Cross-references connect related passages across the Bible, revealing thematic links between Old and New Testament texts.
+
+```ruby
+# List cross-references
+refs = client.list_cross_references
+```
+
+### Study Glossary Terms
+
+Biblical glossary with Hebrew and Greek original words, transliterations, and theological definitions.
+
+```ruby
+# Browse glossary terms
+terms = client.list_glossary
+
+# Look up a specific term
+term = client.get_glossary_term("agape")
+puts term["definition"]
+```
+
+### Walk the Timeline
+
+Biblical chronology organized into eras -- from Creation through the Patriarchs, Exodus, Monarchy, Exile, and into the New Testament period.
+
+```ruby
+# List timeline eras
+eras = client.list_eras
+
+# List events in a specific era
+events = client.list_events(era: "patriarchs")
+```
+
+### Follow Reading Plans
+
+Structured Bible reading plans for systematic study -- daily readings organized into multi-week programs covering different themes or the entire Bible.
+
+```ruby
+# List available reading plans
+plans = client.list_reading_plans
+
+# Get a specific plan with daily entries
+plan = client.get_reading_plan("bible-in-a-year")
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `list_books` | List all 66 Bible books |
+| `get_book(slug)` | Get book details by slug |
+| `list_book_groups` | List book groups (Pentateuch, Gospels, etc.) |
+| `get_book_group(slug)` | Get book group details |
+| `list_translations` | List available translations |
+| `get_translation(code)` | Get translation by code |
+| `list_chapters(book:)` | List chapters, filter by book |
+| `get_verse(book, chapter, verse, translation:)` | Get a specific verse |
+| `search(query, limit:)` | Search verses by keyword |
+| `list_people` | List biblical people |
+| `get_person(slug)` | Get person details |
+| `list_places` | List biblical places |
+| `get_place(slug)` | Get place details |
+| `list_topics` | List thematic topics |
+| `get_topic(slug)` | Get topic with verses |
+| `list_cross_references` | List cross-references |
+| `list_glossary` | List glossary terms |
+| `get_glossary_term(slug)` | Get glossary term definition |
+| `list_eras` | List timeline eras |
+| `list_events(era:)` | List timeline events |
+| `list_reading_plans` | List reading plans |
+| `get_reading_plan(slug)` | Get reading plan details |
+
+## Learn More About the Bible
+
+- **Browse**: [Books of the Bible](https://widebible.com/books/) -- [People](https://widebible.com/people/) -- [Places](https://widebible.com/places/)
+- **Study**: [Topics](https://widebible.com/topics/) -- [Glossary](https://widebible.com/glossary/) -- [Timeline](https://widebible.com/timeline/)
+- **API**: [REST API Docs](https://widebible.com/developers/) -- [OpenAPI Spec](https://widebible.com/api/openapi.json)
+
+## WideHoly Scripture Family
+
+Part of the [WideHoly](https://wideholy.com) multi-religion scripture platform.
+
+| Site | Domain | Focus |
+|------|--------|-------|
+| **WideBible** | [widebible.com](https://widebible.com) | **66 books, 31,102 verses, KJV/ASV/BBE/YLT, cross-references** |
+| WideQuran | [widequran.com](https://widequran.com) | 114 surahs, 6,236 ayahs, hadith collections, tafsir |
+| WideTorah | [widetorah.com](https://widetorah.com) | Tanakh, Talmud tractates, parashot, Rashi commentary |
+| WideGita | [widegita.com](https://widegita.com) | 18 chapters, 700 verses, Upanishads, Yoga Sutras |
+| WideSutra | [widesutra.com](https://widesutra.com) | Tipitaka, Pali Canon, Mahayana sutras, Buddhist figures |
+| WideHoly | [wideholy.com](https://wideholy.com) | Cross-religion search, verse comparison, shared topics |
+
+## Also Available
+
+| Platform | Install | Link |
+|----------|---------|------|
+| **PyPI** | `pip install widebible` | [PyPI](https://pypi.org/project/widebible/) |
+| **npm** | `npm install widebible` | [npm](https://www.npmjs.com/package/widebible) |
+
+## License
+
+MIT

data/lib/widebible/client.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module WideBible
+  # HTTP client for the WideBible REST API.
+  #
+  # Zero runtime dependencies -- uses only Ruby stdlib (net/http, json, uri).
+  #
+  #   client = WideBible::Client.new
+  #   books = client.list_books
+  #   verse = client.get_verse("john", 3, 16)
+  #   results = client.search("love")
+  #
+  class Client
+    DEFAULT_BASE_URL = "https://widebible.com/api/v1/bible"
+    DEFAULT_TIMEOUT  = 10
+
+    def initialize(base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+    end
+
+    # --- Books ----------------------------------------------------------------
+
+    # List all 66 books of the Bible.
+    #
+    # @return [Hash] paginated list of books
+    def list_books(**params)
+      get("/books/", params)
+    end
+
+    # Get book details by slug (e.g. "genesis", "john").
+    #
+    # @param slug [String] book URL slug
+    # @return [Hash] book details
+    def get_book(slug)
+      get("/books/#{slug}/")
+    end
+
+    # --- Book Groups ----------------------------------------------------------
+
+    # List book groups (Pentateuch, Gospels, etc.).
+    #
+    # @return [Hash] paginated list of book groups
+    def list_book_groups(**params)
+      get("/book-groups/", params)
+    end
+
+    # Get book group details by slug.
+    #
+    # @param slug [String] book group slug
+    # @return [Hash] book group details
+    def get_book_group(slug)
+      get("/book-groups/#{slug}/")
+    end
+
+    # --- Translations ---------------------------------------------------------
+
+    # List available Bible translations (KJV, ASV, BBE, YLT).
+    #
+    # @return [Hash] paginated list of translations
+    def list_translations(**params)
+      get("/translations/", params)
+    end
+
+    # Get translation details by code (e.g. "kjv").
+    #
+    # @param code [String] translation code
+    # @return [Hash] translation details
+    def get_translation(code)
+      get("/translations/#{code}/")
+    end
+
+    # --- Chapters -------------------------------------------------------------
+
+    # List chapters, optionally filtered by book slug.
+    #
+    # @param book [String, nil] book slug to filter by
+    # @return [Hash] paginated list of chapters
+    def list_chapters(book: nil, **params)
+      get("/chapters/", { book__slug: book }.merge(params))
+    end
+
+    # --- Verses ---------------------------------------------------------------
+
+    # Get a specific Bible verse by book, chapter, and verse number.
+    #
+    # @param book [String] book slug (e.g. "john", "genesis")
+    # @param chapter [Integer] chapter number
+    # @param verse [Integer] verse number
+    # @param translation [String] translation code (default: "kjv")
+    # @return [Hash] verse data with text, reference, and translation
+    def get_verse(book, chapter, verse, translation: "kjv")
+      get("/verses/", {
+        book__slug: book,
+        chapter: chapter,
+        verse: verse,
+        translation__code: translation
+      })
+    end
+
+    # Search Bible verses by keyword.
+    #
+    # @param query [String] search query string
+    # @param limit [Integer] maximum number of results (default: 25)
+    # @return [Hash] paginated search results
+    def search(query, limit: 25)
+      get("/verses/", { search: query, page_size: limit })
+    end
+
+    # --- People ---------------------------------------------------------------
+
+    # List biblical people (prophets, kings, apostles, etc.).
+    #
+    # @return [Hash] paginated list of people
+    def list_people(**params)
+      get("/people/", params)
+    end
+
+    # Get a biblical person's details by slug.
+    #
+    # @param slug [String] person slug
+    # @return [Hash] person details
+    def get_person(slug)
+      get("/people/#{slug}/")
+    end
+
+    # --- Places ---------------------------------------------------------------
+
+    # List biblical places with geocoded coordinates.
+    #
+    # @return [Hash] paginated list of places
+    def list_places(**params)
+      get("/places/", params)
+    end
+
+    # Get a biblical place's details by slug.
+    #
+    # @param slug [String] place slug
+    # @return [Hash] place details
+    def get_place(slug)
+      get("/places/#{slug}/")
+    end
+
+    # --- Topics ---------------------------------------------------------------
+
+    # List thematic verse collections (love, faith, prayer, etc.).
+    #
+    # @return [Hash] paginated list of topics
+    def list_topics(**params)
+      get("/topics/", params)
+    end
+
+    # Get topic details and associated verses by slug.
+    #
+    # @param slug [String] topic slug
+    # @return [Hash] topic details with verses
+    def get_topic(slug)
+      get("/topics/#{slug}/")
+    end
+
+    # --- Cross-References -----------------------------------------------------
+
+    # List cross-references between Bible passages.
+    #
+    # @return [Hash] paginated list of cross-references
+    def list_cross_references(**params)
+      get("/cross-references/", params)
+    end
+
+    # --- Glossary -------------------------------------------------------------
+
+    # List biblical glossary terms with Hebrew/Greek words.
+    #
+    # @return [Hash] paginated list of glossary terms
+    def list_glossary(**params)
+      get("/glossary/", params)
+    end
+
+    # Get a glossary term's definition by slug.
+    #
+    # @param slug [String] glossary term slug
+    # @return [Hash] glossary term details
+    def get_glossary_term(slug)
+      get("/glossary/#{slug}/")
+    end
+
+    # --- Timeline -------------------------------------------------------------
+
+    # List biblical timeline eras (Patriarchs, Exodus, etc.).
+    #
+    # @return [Hash] paginated list of eras
+    def list_eras(**params)
+      get("/timeline-eras/", params)
+    end
+
+    # List timeline events, optionally filtered by era slug.
+    #
+    # @param era [String, nil] era slug to filter by
+    # @return [Hash] paginated list of events
+    def list_events(era: nil, **params)
+      get("/timeline-events/", { era__slug: era }.merge(params))
+    end
+
+    # --- Reading Plans --------------------------------------------------------
+
+    # List Bible reading plans.
+    #
+    # @return [Hash] paginated list of reading plans
+    def list_reading_plans(**params)
+      get("/reading-plans/", params)
+    end
+
+    # Get a reading plan's details and daily entries by slug.
+    #
+    # @param slug [String] reading plan slug
+    # @return [Hash] reading plan details
+    def get_reading_plan(slug)
+      get("/reading-plans/#{slug}/")
+    end
+
+    private
+
+    def get(path, params = {})
+      uri = URI("#{@base_url}#{path}")
+      cleaned = params.each_with_object({}) { |(k, v), h| h[k] = v unless v.nil? }
+      uri.query = URI.encode_www_form(cleaned) unless cleaned.empty?
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+
+      request = Net::HTTP::Get.new(uri)
+      request["Accept"] = "application/json"
+      request["User-Agent"] = "widebible-rb/#{VERSION}"
+
+      response = http.request(request)
+
+      case response
+      when Net::HTTPSuccess
+        JSON.parse(response.body)
+      when Net::HTTPNotFound
+        raise "Not found: #{path}"
+      else
+        raise "HTTP #{response.code}: #{response.body}"
+      end
+    end
+  end
+end

data/lib/widebible/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WideBible
+  VERSION = "0.1.0"
+end

data/lib/widebible.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "widebible/version"
+require_relative "widebible/client"

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: widebible
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- dobestan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-03-24 00:00:00.000000000 Z
+dependencies: []
+description: API client for widebible.com. Access 66 books, 31,102 verses across 4
+  translations (KJV, ASV, BBE, YLT), biblical people, places, topics, cross-references,
+  glossary, timeline, and reading plans. Zero dependencies.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/widebible.rb
+- lib/widebible/client.rb
+- lib/widebible/version.rb
+homepage: https://widebible.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://widebible.com
+  source_code_uri: https://github.com/dobestan/widebible-rb
+  changelog_uri: https://github.com/dobestan/widebible-rb/blob/main/CHANGELOG.md
+  documentation_uri: https://widebible.com/developers/
+  bug_tracker_uri: https://github.com/dobestan/widebible-rb/issues
+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.0.3.1
+signing_key: 
+specification_version: 4
+summary: Ruby SDK for WideBible — Bible verses, people, places, cross-references
+test_files: []