bibleql-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d7b19f7f5f649f8a05b77edc0649af6fd8d36fa002627f5c514ec4b010dd40c
+  data.tar.gz: de3ae470eaafd050cb00982688c2bef14eba3be6dc0ee0131d7ce5a10be16a8a
+SHA512:
+  metadata.gz: 6687cad36d04efe03e7f0be1bde2000497fc039619d395bb3394006a237a7f168d18afdbd2f1f39b6d19e2653ab560018beafe4bf7c3ab4d94328a6b2a787c32
+  data.tar.gz: f3859573ec3389c3f1a472f350b37765fb40078957a6f7c043ee9aa5dd6510badd330d49f4da3e9cb1aa6e1d0205808d567769301ec3e23cff604494f72f64cd

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-05
+
+- Initial release

data/CLAUDE.md

@@ -0,0 +1,113 @@
+# CLAUDE.md — BibleQL Ruby Gem
+
+## What is this project?
+
+`bibleql-ruby` is a Ruby client gem for the BibleQL GraphQL API. It lets Ruby developers query Bible verses, passages, and translations without writing GraphQL directly.
+
+- **Gem name**: `bibleql-ruby` (require as `bibleql`)
+- **Top-level module**: `BibleQL` (capital Q, capital L)
+- **HTTP client**: Faraday (~> 2.0)
+- **Production API**: `https://bibleql-rails.onrender.com/graphql` (configurable, may change when domain is purchased)
+- **Auth**: `Authorization: Bearer <api_key>` header on every request. API key is required.
+- **Source GraphQL API**: lives at `/Users/lporras/apps/lporras/bibleql` — check there for schema changes
+
+## Commands
+
+```bash
+bundle exec rspec          # run all tests (49 specs)
+bundle exec rspec spec/bibleql/client_spec.rb  # run specific spec file
+bundle exec rubocop        # lint check
+bundle exec rubocop -A     # auto-fix lint issues
+bundle exec rake           # runs both rspec + rubocop (default task)
+```
+
+## Architecture
+
+```
+lib/bibleql.rb                  # Entry point: BibleQL.configure, .client, .reset!
+lib/bibleql/version.rb          # BibleQL::VERSION
+lib/bibleql/configuration.rb    # Holds api_key, api_url, default_translation, timeout
+lib/bibleql/errors.rb           # Error hierarchy (see below)
+lib/bibleql/resource.rb         # Base class: to_h, ==, inspect for all resources
+lib/bibleql/resources/*.rb      # Data objects: Verse, Passage, Translation, Book, Language, LocalizedBook, Chapter, SearchResult
+lib/bibleql/query_builder.rb    # Module with class methods returning {query:, variables:} hashes
+lib/bibleql/client.rb           # Main class: 11 public methods, each calls QueryBuilder -> execute -> map to resources
+```
+
+### Data flow for a client method
+
+1. **Client public method** (e.g. `#passage`) resolves translation, calls `QueryBuilder.passage(...)`.
+2. **QueryBuilder** returns `{ query: "...", variables: { ... } }` with hardcoded GraphQL string.
+3. **Client#execute** POSTs to API via Faraday, parses JSON, checks for HTTP/GraphQL errors.
+4. **Client#map_*  methods** convert camelCase JSON keys to snake_case hashes.
+5. **Resource constructor** receives the hash, sets attributes via `attr_accessor`.
+
+### Error hierarchy
+
+```
+BibleQL::Error < StandardError
+  ├── ConfigurationError        # missing api_key
+  ├── ConnectionError           # network failures
+  │   └── TimeoutError          # request timeout
+  ├── APIError (status, body)   # generic HTTP error
+  │   ├── AuthenticationError   # 401
+  │   ├── RateLimitError        # 429
+  │   └── ServerError           # 5xx
+  └── QueryError (errors array) # GraphQL errors in response
+      └── NotFoundError         # "not found" in error message
+```
+
+### Naming conventions
+
+- **GraphQL fields**: camelCase (e.g. `bookId`, `translationName`, `verseCount`)
+- **Ruby attributes**: snake_case (e.g. `book_id`, `translation_name`, `verse_count`)
+- **Mapping**: done in `Client#map_*` private methods (e.g. `map_verse`, `map_passage`)
+
+## How to add a new API query
+
+1. **Check the GraphQL schema** at `/Users/lporras/apps/lporras/bibleql/app/graphql/types/query_type.rb` for the query name, arguments, and return type.
+2. **Add a method to `QueryBuilder`** (`lib/bibleql/query_builder.rb`): return `{ query: "...", variables: { ... } }`. Use camelCase in the GraphQL string.
+3. **Add a public method to `Client`** (`lib/bibleql/client.rb`): call the QueryBuilder, execute, map response to resource objects. Add a `map_*` private method if the response has a new shape.
+4. **Add/update Resource** if needed (`lib/bibleql/resources/`): create a new class extending `Resource` with `attr_accessor` for each field. For nested objects, define a custom setter (see `Passage#verses=`).
+5. **Register the resource** in `lib/bibleql.rb` with `require_relative`.
+6. **Write tests**:
+   - `spec/bibleql/query_builder_spec.rb` — verify variables and query string.
+   - `spec/bibleql/client_spec.rb` — stub with `stub_graphql_success(...)` helper, assert return types.
+   - `spec/bibleql/resources/*_spec.rb` — if new resource, test construction and nested wrapping.
+
+## How to add a new Resource
+
+1. Create `lib/bibleql/resources/my_thing.rb`:
+   ```ruby
+   module BibleQL
+     class MyThing < Resource
+       attr_accessor :field_one, :field_two
+     end
+   end
+   ```
+2. For nested resources, define a custom setter:
+   ```ruby
+   attr_reader :items
+   def items=(list)
+     @items = (list || []).map { |i| i.is_a?(Item) ? i : Item.new(i) }
+   end
+   ```
+3. Add `require_relative "bibleql/resources/my_thing"` to `lib/bibleql.rb`.
+
+## Testing patterns
+
+- **WebMock** blocks all real HTTP. Specs use three helpers in `client_spec.rb`:
+  - `stub_graphql_success(data_hash)` — 200 with `{"data": ...}`
+  - `stub_graphql_errors(errors_array)` — 200 with `{"data": null, "errors": [...]}`
+  - `stub_graphql_http_error(status)` — non-200 HTTP response
+- **BibleQL.reset!** is called `before(:each)` in `spec_helper.rb`.
+- Client specs must pass `api_key: "test_key"` to `Client.new`.
+- Use `expect_with :rspec` syntax only (no `should`).
+
+## Style
+
+- `frozen_string_literal: true` on every Ruby file.
+- Double quotes for strings (enforced by rubocop).
+- No documentation cops (Style/Documentation is disabled).
+- `query_builder.rb` is exempt from MethodLength (GraphQL strings are long).
+- Specs are exempt from BlockLength and LineLength.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"bibleql-ruby" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["lporras16@gmail.com"](mailto:"lporras16@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Luis Porras
+
+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,160 @@
+# BibleQL Ruby
+
+An idiomatic Ruby client for the [BibleQL](https://bibleql-rails.onrender.com) GraphQL API. Query Bible verses, passages, and translations across ~43 translations without writing GraphQL.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "bibleql-ruby"
+```
+
+Then run `bundle install`, or install directly:
+
+```
+gem install bibleql-ruby
+```
+
+## Configuration
+
+```ruby
+require "bibleql"
+
+BibleQL.configure do |config|
+  config.api_key = "bql_live_..."             # required - your BibleQL API key
+  config.default_translation = "spa-bes"      # optional, defaults to "eng-web"
+  config.api_url = "https://custom-host.com/graphql"  # optional, defaults to production
+  config.timeout = 60                         # optional, defaults to 30 seconds
+end
+```
+
+## Usage
+
+```ruby
+client = BibleQL.client
+# or with per-instance config:
+client = BibleQL::Client.new(api_key: "bql_live_...", default_translation: "spa-bes")
+```
+
+### Passages
+
+```ruby
+passage = client.passage("John 3:16")
+passage.reference       # => "John 3:16"
+passage.text            # => "For God so loved the world..."
+passage.verses          # => [#<BibleQL::Verse ...>]
+passage.translation_id  # => "eng-web"
+
+# With a specific translation
+client.passage("Juan 3:16", translation: "spa-bes")
+```
+
+### Verses
+
+```ruby
+verse = client.verse("MAT", 5, 3)
+verse.book_name  # => "Matthew"
+verse.chapter    # => 5
+verse.verse      # => 3
+verse.text       # => "Blessed are the poor in spirit..."
+```
+
+### Chapters
+
+```ruby
+verses = client.chapter("MAT", 5)
+# => [#<BibleQL::Verse ...>, ...]
+```
+
+### Random Verse
+
+```ruby
+client.random_verse
+client.random_verse(testament: "NT")
+client.random_verse(books: "PSA")
+```
+
+### Search
+
+```ruby
+results = client.search("love", limit: 10)
+# => [#<BibleQL::Verse ...>, ...]
+```
+
+### Verse of the Day
+
+```ruby
+passage = client.verse_of_the_day
+passage = client.verse_of_the_day(date: "2026-01-01")
+```
+
+### Translations
+
+```ruby
+translations = client.translations
+# => [#<BibleQL::Translation identifier="eng-web" ...>, ...]
+
+translation = client.translation("eng-web")
+translation.name   # => "World English Bible"
+translation.books  # => [#<BibleQL::LocalizedBook ...>, ...]
+```
+
+### Languages
+
+```ruby
+languages = client.languages
+languages.first.code              # => "eng"
+languages.first.translation_count # => 5
+languages.first.translations      # => [#<BibleQL::Translation ...>, ...]
+```
+
+### Books
+
+```ruby
+books = client.books
+# => [#<BibleQL::Book book_id="GEN" name="Genesis" ...>, ...]
+```
+
+### Bible Index
+
+```ruby
+index = client.bible_index
+# => [#<BibleQL::LocalizedBook ...>, ...]
+index.first.chapters  # => [#<BibleQL::Chapter number=1 verse_count=31>, ...]
+```
+
+## Error Handling
+
+```ruby
+begin
+  client.passage("Invalid Reference")
+rescue BibleQL::NotFoundError => e
+  puts "Not found: #{e.message}"
+rescue BibleQL::AuthenticationError
+  puts "Invalid API key"
+rescue BibleQL::RateLimitError
+  puts "Too many requests"
+rescue BibleQL::ServerError
+  puts "Server error"
+rescue BibleQL::TimeoutError
+  puts "Request timed out"
+rescue BibleQL::ConnectionError
+  puts "Connection failed"
+rescue BibleQL::QueryError => e
+  puts "GraphQL error: #{e.message}"
+  puts e.errors  # raw error array from GraphQL
+end
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # run tests
+bundle exec rubocop    # run linter
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/bibleql/client.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module BibleQL
+  class Client
+    def initialize(api_key: nil, default_translation: nil, api_url: nil, timeout: nil)
+      config = BibleQL.configuration
+      @api_key = api_key || config.api_key
+      @default_translation = default_translation || config.default_translation
+      @api_url = api_url || config.api_url
+      @timeout = timeout || config.timeout
+
+      raise ConfigurationError, "api_key is required. Set it via BibleQL.configure or pass it to Client.new" unless @api_key
+
+      @connection = Faraday.new(url: @api_url) do |f|
+        f.options.timeout = @timeout
+        f.options.open_timeout = @timeout
+        f.headers["Content-Type"] = "application/json"
+        f.headers["Authorization"] = "Bearer #{@api_key}"
+      end
+    end
+
+    def translations
+      data = execute(QueryBuilder.translations, "translations")
+      data["translations"].map { |t| Translation.new(map_translation(t)) }
+    end
+
+    def translation(identifier)
+      data = execute(QueryBuilder.translation(identifier), "translation")
+      Translation.new(map_translation(data["translation"]))
+    end
+
+    def books
+      data = execute(QueryBuilder.books, "books")
+      data["books"].map { |b| Book.new(map_book(b)) }
+    end
+
+    def languages
+      data = execute(QueryBuilder.languages, "languages")
+      data["languages"].map { |l| Language.new(map_language(l)) }
+    end
+
+    def passage(reference, translation: nil)
+      t = translation || @default_translation
+      data = execute(QueryBuilder.passage(reference, translation: t), "passage")
+      Passage.new(map_passage(data["passage"]))
+    end
+
+    def chapter(book, chapter_num, translation: nil)
+      t = translation || @default_translation
+      data = execute(QueryBuilder.chapter(book, chapter_num, translation: t), "chapter")
+      data["chapter"].map { |v| Verse.new(map_verse(v)) }
+    end
+
+    def verse(book, chapter_num, verse_num, translation: nil)
+      t = translation || @default_translation
+      data = execute(QueryBuilder.verse(book, chapter_num, verse_num, translation: t), "verse")
+      Verse.new(map_verse(data["verse"]))
+    end
+
+    def random_verse(translation: nil, testament: nil, books: nil)
+      t = translation || @default_translation
+      data = execute(QueryBuilder.random_verse(translation: t, testament: testament, books: books), "randomVerse")
+      Verse.new(map_verse(data["randomVerse"]))
+    end
+
+    def search(query_text, translation: nil, limit: nil)
+      t = translation || @default_translation
+      data = execute(QueryBuilder.search(query_text, translation: t, limit: limit), "search")
+      data["search"].map { |v| Verse.new(map_verse(v)) }
+    end
+
+    def verse_of_the_day(translation: nil, date: nil)
+      t = translation || @default_translation
+      data = execute(QueryBuilder.verse_of_the_day(translation: t, date: date), "verseOfTheDay")
+      Passage.new(map_passage(data["verseOfTheDay"]))
+    end
+
+    def bible_index(translation: nil)
+      t = translation || @default_translation
+      data = execute(QueryBuilder.bible_index(translation: t), "bibleIndex")
+      data["bibleIndex"].map { |b| LocalizedBook.new(map_localized_book(b)) }
+    end
+
+    private
+
+    def execute(query_hash, _query_name)
+      response = @connection.post do |req|
+        req.body = JSON.generate(query: query_hash[:query], variables: query_hash[:variables])
+      end
+
+      handle_http_errors(response)
+
+      body = JSON.parse(response.body)
+
+      handle_graphql_errors(body["errors"]) if body["errors"] && !body["errors"].empty?
+
+      body["data"]
+    rescue Faraday::TimeoutError => e
+      raise TimeoutError, "Request timed out: #{e.message}"
+    rescue Faraday::ConnectionFailed, Faraday::Error => e
+      raise ConnectionError, "Connection failed: #{e.message}"
+    end
+
+    def handle_http_errors(response)
+      return if response.status >= 200 && response.status < 300
+
+      message = "HTTP #{response.status}"
+      case response.status
+      when 401
+        raise AuthenticationError.new(message, status: response.status, body: response.body)
+      when 429
+        raise RateLimitError.new(message, status: response.status, body: response.body)
+      when 500..599
+        raise ServerError.new(message, status: response.status, body: response.body)
+      else
+        raise APIError.new(message, status: response.status, body: response.body)
+      end
+    end
+
+    def handle_graphql_errors(errors)
+      messages = errors.map { |e| e["message"] }
+      full_message = messages.join("; ")
+
+      raise NotFoundError.new(full_message, errors: errors) if messages.any? { |m| m.downcase.include?("not found") }
+
+      raise QueryError.new(full_message, errors: errors)
+    end
+
+    def map_verse(data)
+      {
+        book_id: data["bookId"],
+        book_name: data["bookName"],
+        chapter: data["chapter"],
+        verse: data["verse"],
+        text: data["text"]
+      }
+    end
+
+    def map_passage(data)
+      {
+        reference: data["reference"],
+        translation_id: data["translationId"],
+        translation_name: data["translationName"],
+        translation_note: data["translationNote"],
+        text: data["text"],
+        verses: (data["verses"] || []).map { |v| map_verse(v) }
+      }
+    end
+
+    def map_translation(data)
+      result = {
+        identifier: data["identifier"],
+        name: data["name"],
+        language: data["language"],
+        note: data["note"]
+      }
+      result[:books] = data["books"].map { |b| map_localized_book(b) } if data["books"]
+      result
+    end
+
+    def map_book(data)
+      {
+        book_id: data["bookId"],
+        name: data["name"],
+        testament: data["testament"],
+        position: data["position"]
+      }
+    end
+
+    def map_language(data)
+      {
+        code: data["code"],
+        translation_count: data["translationCount"],
+        translations: (data["translations"] || []).map { |t| map_translation(t) }
+      }
+    end
+
+    def map_localized_book(data)
+      result = {
+        book_id: data["bookId"],
+        name: data["name"],
+        testament: data["testament"],
+        position: data["position"],
+        chapter_count: data["chapterCount"]
+      }
+      result[:chapters] = data["chapters"].map { |c| map_chapter(c) } if data["chapters"]
+      result
+    end
+
+    def map_chapter(data)
+      result = {
+        number: data["number"],
+        verse_count: data["verseCount"]
+      }
+      result[:verses] = data["verses"].map { |v| map_verse(v) } if data["verses"]
+      result
+    end
+  end
+end

data/lib/bibleql/configuration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class Configuration
+    attr_accessor :api_key, :api_url, :default_translation, :timeout
+
+    DEFAULT_API_URL = "https://bibleql-rails.onrender.com/graphql"
+    DEFAULT_TRANSLATION = "eng-web"
+    DEFAULT_TIMEOUT = 30
+
+    def initialize
+      @api_key = nil
+      @api_url = DEFAULT_API_URL
+      @default_translation = DEFAULT_TRANSLATION
+      @timeout = DEFAULT_TIMEOUT
+    end
+  end
+end

data/lib/bibleql/errors.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class ConnectionError < Error; end
+
+  class TimeoutError < ConnectionError; end
+
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+
+  class AuthenticationError < APIError; end
+
+  class RateLimitError < APIError; end
+
+  class ServerError < APIError; end
+
+  class QueryError < Error
+    attr_reader :errors
+
+    def initialize(message = nil, errors: [])
+      @errors = errors
+      super(message)
+    end
+  end
+
+  class NotFoundError < QueryError; end
+end

data/lib/bibleql/query_builder.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+module BibleQL
+  module QueryBuilder
+    module_function
+
+    def translations
+      {
+        query: <<~GQL,
+          query {
+            translations {
+              identifier
+              name
+              language
+              note
+            }
+          }
+        GQL
+        variables: {}
+      }
+    end
+
+    def translation(identifier)
+      {
+        query: <<~GQL,
+          query($identifier: String!) {
+            translation(identifier: $identifier) {
+              identifier
+              name
+              language
+              note
+              books {
+                bookId
+                name
+                testament
+                position
+                chapterCount
+              }
+            }
+          }
+        GQL
+        variables: { identifier: identifier }
+      }
+    end
+
+    def books
+      {
+        query: <<~GQL,
+          query {
+            books {
+              bookId
+              name
+              testament
+              position
+            }
+          }
+        GQL
+        variables: {}
+      }
+    end
+
+    def languages
+      {
+        query: <<~GQL,
+          query {
+            languages {
+              code
+              translationCount
+              translations {
+                identifier
+                name
+                language
+                note
+              }
+            }
+          }
+        GQL
+        variables: {}
+      }
+    end
+
+    def passage(reference, translation:)
+      {
+        query: <<~GQL,
+          query($reference: String!, $translation: String) {
+            passage(reference: $reference, translation: $translation) {
+              reference
+              translationId
+              translationName
+              translationNote
+              text
+              verses {
+                bookId
+                bookName
+                chapter
+                verse
+                text
+              }
+            }
+          }
+        GQL
+        variables: { reference: reference, translation: translation }
+      }
+    end
+
+    def chapter(book, chapter, translation:)
+      {
+        query: <<~GQL,
+          query($book: String!, $chapter: Int!, $translation: String) {
+            chapter(book: $book, chapter: $chapter, translation: $translation) {
+              bookId
+              bookName
+              chapter
+              verse
+              text
+            }
+          }
+        GQL
+        variables: { book: book, chapter: chapter, translation: translation }
+      }
+    end
+
+    def verse(book, chapter, verse, translation:)
+      {
+        query: <<~GQL,
+          query($book: String!, $chapter: Int!, $verse: Int!, $translation: String) {
+            verse(book: $book, chapter: $chapter, verse: $verse, translation: $translation) {
+              bookId
+              bookName
+              chapter
+              verse
+              text
+            }
+          }
+        GQL
+        variables: { book: book, chapter: chapter, verse: verse, translation: translation }
+      }
+    end
+
+    def random_verse(translation:, testament: nil, books: nil)
+      {
+        query: <<~GQL,
+          query($translation: String, $testament: String, $books: String) {
+            randomVerse(translation: $translation, testament: $testament, books: $books) {
+              bookId
+              bookName
+              chapter
+              verse
+              text
+            }
+          }
+        GQL
+        variables: { translation: translation, testament: testament, books: books }.compact
+      }
+    end
+
+    def search(query_text, translation:, limit: nil)
+      {
+        query: <<~GQL,
+          query($query: String!, $translation: String, $limit: Int) {
+            search(query: $query, translation: $translation, limit: $limit) {
+              bookId
+              bookName
+              chapter
+              verse
+              text
+            }
+          }
+        GQL
+        variables: { query: query_text, translation: translation, limit: limit }.compact
+      }
+    end
+
+    def verse_of_the_day(translation:, date: nil)
+      {
+        query: <<~GQL,
+          query($translation: String, $date: ISO8601Date) {
+            verseOfTheDay(translation: $translation, date: $date) {
+              reference
+              translationId
+              translationName
+              translationNote
+              text
+              verses {
+                bookId
+                bookName
+                chapter
+                verse
+                text
+              }
+            }
+          }
+        GQL
+        variables: { translation: translation, date: date }.compact
+      }
+    end
+
+    def bible_index(translation:)
+      {
+        query: <<~GQL,
+          query($translation: String) {
+            bibleIndex(translation: $translation) {
+              bookId
+              name
+              testament
+              position
+              chapterCount
+              chapters {
+                number
+                verseCount
+              }
+            }
+          }
+        GQL
+        variables: { translation: translation }
+      }
+    end
+  end
+end

data/lib/bibleql/resource.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class Resource
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        setter = "#{key}="
+        public_send(setter, value) if respond_to?(setter)
+      end
+    end
+
+    def to_h
+      instance_variables.each_with_object({}) do |ivar, hash|
+        key = ivar.to_s.delete_prefix("@").to_sym
+        value = instance_variable_get(ivar)
+        hash[key] = value.is_a?(Resource) ? value.to_h : value
+      end
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && to_h == other.to_h
+    end
+
+    def to_s
+      "#<#{self.class.name} #{to_h.map { |k, v| "#{k}=#{v.inspect}" }.join(", ")}>"
+    end
+
+    alias inspect to_s
+  end
+end

data/lib/bibleql/resources/book.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class Book < Resource
+    attr_accessor :book_id, :name, :testament, :position
+  end
+end

data/lib/bibleql/resources/chapter.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class Chapter < Resource
+    attr_accessor :number, :verse_count
+
+    attr_reader :verses
+
+    def verses=(list)
+      @verses = (list || []).map do |v|
+        v.is_a?(Verse) ? v : Verse.new(v)
+      end
+    end
+  end
+end

data/lib/bibleql/resources/language.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class Language < Resource
+    attr_accessor :code, :translation_count
+
+    attr_reader :translations
+
+    def translations=(list)
+      @translations = (list || []).map do |t|
+        t.is_a?(Translation) ? t : Translation.new(t)
+      end
+    end
+  end
+end

data/lib/bibleql/resources/localized_book.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class LocalizedBook < Resource
+    attr_accessor :book_id, :name, :testament, :position, :chapter_count
+
+    attr_reader :chapters
+
+    def chapters=(list)
+      @chapters = (list || []).map do |c|
+        c.is_a?(Chapter) ? c : Chapter.new(c)
+      end
+    end
+  end
+end

data/lib/bibleql/resources/passage.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class Passage < Resource
+    attr_accessor :reference, :translation_id, :translation_name, :translation_note, :text
+
+    attr_reader :verses
+
+    def verses=(list)
+      @verses = (list || []).map do |v|
+        v.is_a?(Verse) ? v : Verse.new(v)
+      end
+    end
+  end
+end

data/lib/bibleql/resources/search_result.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class SearchResult < Resource
+    attr_accessor :total_count
+
+    attr_reader :verses
+
+    def verses=(list)
+      @verses = (list || []).map do |v|
+        v.is_a?(Verse) ? v : Verse.new(v)
+      end
+    end
+  end
+end

data/lib/bibleql/resources/translation.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class Translation < Resource
+    attr_accessor :identifier, :name, :language, :note
+
+    attr_reader :books
+
+    def books=(list)
+      @books = (list || []).map do |b|
+        b.is_a?(LocalizedBook) ? b : LocalizedBook.new(b)
+      end
+    end
+  end
+end

data/lib/bibleql/resources/verse.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BibleQL
+  class Verse < Resource
+    attr_accessor :book_id, :book_name, :chapter, :verse, :text
+  end
+end

data/lib/bibleql/version.rb

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

data/lib/bibleql.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "bibleql/version"
+require_relative "bibleql/configuration"
+require_relative "bibleql/errors"
+require_relative "bibleql/resource"
+require_relative "bibleql/resources/verse"
+require_relative "bibleql/resources/passage"
+require_relative "bibleql/resources/translation"
+require_relative "bibleql/resources/book"
+require_relative "bibleql/resources/language"
+require_relative "bibleql/resources/localized_book"
+require_relative "bibleql/resources/chapter"
+require_relative "bibleql/resources/search_result"
+require_relative "bibleql/query_builder"
+require_relative "bibleql/client"
+
+module BibleQL
+  class << self
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def client
+      Client.new
+    end
+
+    def reset!
+      @configuration = Configuration.new
+    end
+  end
+end

data/sig/bibleql/ruby.rbs

@@ -0,0 +1,6 @@
+module Bibleql
+  module Ruby
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: bibleql-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Luis Porras
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  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'
+description: An idiomatic Ruby client for querying Bible verses, passages, and translations
+  via the BibleQL GraphQL API.
+email:
+- lporras16@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CLAUDE.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/bibleql.rb
+- lib/bibleql/client.rb
+- lib/bibleql/configuration.rb
+- lib/bibleql/errors.rb
+- lib/bibleql/query_builder.rb
+- lib/bibleql/resource.rb
+- lib/bibleql/resources/book.rb
+- lib/bibleql/resources/chapter.rb
+- lib/bibleql/resources/language.rb
+- lib/bibleql/resources/localized_book.rb
+- lib/bibleql/resources/passage.rb
+- lib/bibleql/resources/search_result.rb
+- lib/bibleql/resources/translation.rb
+- lib/bibleql/resources/verse.rb
+- lib/bibleql/version.rb
+- sig/bibleql/ruby.rbs
+homepage: https://github.com/lporras/bibleql-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/lporras/bibleql-ruby
+  source_code_uri: https://github.com/lporras/bibleql-ruby
+  changelog_uri: https://github.com/lporras/bibleql-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby client for the BibleQL GraphQL API
+test_files: []