widequran 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ae08237e178eee1834cca2b65436ffdb4c316f6b7ac0a0b5f7b8ab7bee5ffd59
+  data.tar.gz: 4223d14cafaffc9ee6aaa5c850259cbfad1b1a6cfff1bb507833a95e33a27eff
+SHA512:
+  metadata.gz: 5426184bfe78dfa791d65cbe7568fa244bb592cd0aec5e31be7aa9dc55fcacb206b631a2bcf570473055bc8802d077054e73a6dcc0e0cfd67514bfdcef5c72b7
+  data.tar.gz: d8be5c7c879c3805e73b085dd0299e6b1f72882cd0d008aba1a1efc5fcd24b61bdb8049ad1eb775738c215e00790c59cac55441a1bd9e3ffcda4dacd6b0ba8d6

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,258 @@
+# widequran
+
+[![Gem Version](https://badge.fury.io/rb/widequran.svg)](https://rubygems.org/gems/widequran)
+[![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/widequran)
+
+Ruby client for the [WideQuran](https://widequran.com) API. Access all 114 surahs, 6,236 ayahs with multiple translations, hadith collections (Bukhari, Muslim, Abu Dawud), tafsir commentary (Ibn Kathir, Al-Jalalayn), juz and hizb divisions, Quranic figures, Islamic topics, and Arabic glossary terms. Zero runtime dependencies -- uses only Ruby stdlib (`net/http`, `json`, `uri`).
+
+WideQuran is a comprehensive Quran encyclopedia providing structured scripture data with Arabic text, transliterations, and scholarly translations -- all accessible through a free REST API.
+
+> **Explore the Quran at [widequran.com](https://widequran.com)** -- [Surahs](https://widequran.com/surahs/), [Hadith](https://widequran.com/hadith/), [Tafsir](https://widequran.com/tafsir/), [People](https://widequran.com/people/), [Glossary](https://widequran.com/glossary/)
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [What You Can Do](#what-you-can-do)
+  - [Browse Surahs](#browse-surahs)
+  - [Read Ayahs](#read-ayahs)
+  - [Search Scripture](#search-scripture)
+  - [Navigate Juz and Hizb](#navigate-juz-and-hizb)
+  - [Study Tafsir Commentary](#study-tafsir-commentary)
+  - [Explore Hadith Collections](#explore-hadith-collections)
+  - [Discover Quranic Figures](#discover-quranic-figures)
+  - [Browse Topics and Glossary](#browse-topics-and-glossary)
+- [API Reference](#api-reference)
+- [Learn More About the Quran](#learn-more-about-the-quran)
+- [WideHoly Scripture Family](#wideholy-scripture-family)
+- [Also Available](#also-available)
+- [License](#license)
+
+## Install
+
+```bash
+gem install widequran
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "widequran"
+```
+
+## Quick Start
+
+```ruby
+require "widequran"
+
+# Create a client (zero configuration needed)
+client = WideQuran::Client.new
+
+# List all 114 surahs of the Quran
+surahs = client.list_surahs
+puts surahs["results"].first["name"]  # => "Al-Fatihah"
+
+# Search ayahs for a keyword
+results = client.search("mercy")
+results["results"].each { |a| puts a["text"] }
+
+# Filter surahs by revelation type
+meccan = client.list_surahs(revelation_type: "meccan")
+```
+
+## What You Can Do
+
+### Browse Surahs
+
+The Quran contains 114 surahs (chapters), classified as Meccan (revealed in Mecca, 86 surahs) or Medinan (revealed in Medina, 28 surahs). Each surah has a name in Arabic and English, verse count, and revelation context.
+
+```ruby
+# List all surahs
+surahs = client.list_surahs
+
+# Get details for Al-Fatihah (The Opening)
+fatihah = client.get_surah("al-fatihah")
+puts fatihah["name"]         # => "Al-Fatihah"
+puts fatihah["ayah_count"]   # => 7
+
+# Filter by revelation type
+medinan = client.list_surahs(revelation_type: "medinan")
+```
+
+### Read Ayahs
+
+WideQuran provides 6,236 ayahs (verses) with Arabic text and multiple scholarly translations. Each ayah includes surah context, verse number, and translation metadata.
+
+```ruby
+# List ayahs for a specific surah
+ayahs = client.list_ayahs(surah: "al-fatihah")
+
+# Get a specific ayah by ID
+ayah = client.get_ayah(1)
+puts ayah["text"]
+
+# Filter by translation
+ayahs = client.list_ayahs(surah: "al-baqarah", translation: "sahih")
+```
+
+### Search Scripture
+
+Full-text search across all Quran ayahs with optional surah restriction.
+
+```ruby
+# Search across the entire Quran
+results = client.search("mercy")
+results["results"].each do |ayah|
+  puts "#{ayah["surah_name"]} #{ayah["ayah_number"]}: #{ayah["text"]}"
+end
+
+# Search within a specific surah
+results = client.search("believers", surah: "al-baqarah")
+```
+
+### Navigate Juz and Hizb
+
+The Quran is divided into 30 juz (parts) for structured reading, each further split into hizb (half-juz) markers -- a system used for completing the Quran in Ramadan.
+
+```ruby
+# List all 30 juz
+juz_list = client.list_juz
+
+# Get details for juz 1
+juz = client.get_juz(1)
+
+# List hizb markers
+hizbs = client.list_hizbs
+hizb = client.get_hizb(1)
+```
+
+### Study Tafsir Commentary
+
+Tafsir (exegesis) provides scholarly interpretation of Quranic verses. WideQuran includes major commentary collections like Ibn Kathir and Al-Jalalayn.
+
+```ruby
+# List available tafsir collections
+tafsirs = client.list_tafsirs
+
+# Get details for Ibn Kathir's tafsir
+ibn_kathir = client.get_tafsir("ibn-kathir")
+
+# List commentary entries for a surah
+entries = client.list_tafsir_entries(tafsir: "ibn-kathir", surah: "al-fatihah")
+```
+
+### Explore Hadith Collections
+
+Hadith are recorded sayings and actions of Prophet Muhammad. WideQuran provides access to the six canonical collections (Kutub al-Sittah) with authentication grades.
+
+| Collection | Compiler | Hadiths |
+|------------|----------|---------|
+| Sahih al-Bukhari | Imam al-Bukhari | 7,275 |
+| Sahih Muslim | Imam Muslim | 7,453 |
+| Sunan Abu Dawud | Abu Dawud | 5,274 |
+| Jami at-Tirmidhi | At-Tirmidhi | 3,956 |
+| Sunan an-Nasai | An-Nasai | 5,758 |
+| Sunan Ibn Majah | Ibn Majah | 4,341 |
+
+```ruby
+# List hadith collections
+collections = client.list_hadith_collections
+
+# List hadiths from Bukhari
+hadiths = client.list_hadiths(collection: "bukhari")
+
+# Search hadith texts
+results = client.search_hadith("prayer", collection: "muslim")
+```
+
+### Discover Quranic Figures
+
+Profiles of prophets and figures mentioned in the Quran, including Ibrahim, Musa, Isa, and Muhammad (peace be upon them all).
+
+```ruby
+# List all Quranic people
+people = client.list_people
+
+# Filter to prophets only
+prophets = client.list_people(is_prophet: true)
+
+# Get details for a specific person
+ibrahim = client.get_person("ibrahim")
+```
+
+### Browse Topics and Glossary
+
+Thematic collections of ayahs by topic (mercy, justice, patience) and an Arabic-English glossary of Islamic terms.
+
+```ruby
+# List topics
+topics = client.list_topics
+topic = client.get_topic("mercy")
+
+# Browse glossary terms
+terms = client.list_glossary
+term = client.get_term("tawakkul")
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `list_surahs(revelation_type:)` | List all 114 surahs |
+| `get_surah(slug)` | Get surah details |
+| `list_translations(language:)` | List available translations |
+| `get_translation(code)` | Get translation details |
+| `list_ayahs(surah:, translation:)` | List ayahs with filters |
+| `get_ayah(ayah_id)` | Get a specific ayah |
+| `search(query, surah:)` | Search ayahs by keyword |
+| `list_juz` | List all 30 juz |
+| `get_juz(number)` | Get juz details |
+| `list_hizbs(juz:)` | List hizb markers |
+| `get_hizb(number)` | Get hizb details |
+| `list_tafsirs` | List tafsir collections |
+| `get_tafsir(slug)` | Get tafsir details |
+| `list_tafsir_entries(tafsir:, surah:)` | List commentary entries |
+| `get_tafsir_entry(entry_id)` | Get a tafsir entry |
+| `list_hadith_collections` | List hadith collections |
+| `get_hadith_collection(slug)` | Get collection details |
+| `list_hadiths(collection:, grade:)` | List hadiths |
+| `get_hadith(hadith_id)` | Get a specific hadith |
+| `search_hadith(query, collection:)` | Search hadith texts |
+| `list_people(is_prophet:)` | List Quranic figures |
+| `get_person(slug)` | Get person details |
+| `list_topics` | List Quranic topics |
+| `get_topic(slug)` | Get topic details |
+| `list_glossary` | List glossary terms |
+| `get_term(slug)` | Get term definition |
+
+## Learn More About the Quran
+
+- **Browse**: [Surahs](https://widequran.com/surahs/) -- [Hadith Collections](https://widequran.com/hadith/) -- [People](https://widequran.com/people/)
+- **Study**: [Tafsir](https://widequran.com/tafsir/) -- [Topics](https://widequran.com/topics/) -- [Glossary](https://widequran.com/glossary/)
+- **API**: [REST API Docs](https://widequran.com/developers/) -- [OpenAPI Spec](https://widequran.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 widequran` | [PyPI](https://pypi.org/project/widequran/) |
+| **npm** | `npm install widequran` | [npm](https://www.npmjs.com/package/widequran) |
+
+## License
+
+MIT

data/lib/widequran/client.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module WideQuran
+  # HTTP client for the WideQuran REST API.
+  #
+  # Zero runtime dependencies -- uses only Ruby stdlib (net/http, json, uri).
+  #
+  #   client = WideQuran::Client.new
+  #   surahs = client.list_surahs
+  #   ayahs = client.search("mercy")
+  #
+  class Client
+    DEFAULT_BASE_URL = "https://widequran.com/api/v1/quran"
+    DEFAULT_TIMEOUT  = 10
+
+    def initialize(base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+    end
+
+    # --- Surahs ---------------------------------------------------------------
+
+    # List all 114 surahs of the Quran.
+    #
+    # @param revelation_type [String, nil] filter by "meccan" or "medinan"
+    # @return [Hash] paginated list of surahs
+    def list_surahs(revelation_type: nil, **params)
+      get("/surahs/", { revelation_type: revelation_type }.merge(params))
+    end
+
+    # Get surah details by slug (e.g. "al-fatihah").
+    #
+    # @param slug [String] surah URL slug
+    # @return [Hash] surah details
+    def get_surah(slug)
+      get("/surahs/#{slug}/")
+    end
+
+    # --- Translations ---------------------------------------------------------
+
+    # List available Quran translations.
+    #
+    # @param language [String, nil] filter by language code (e.g. "en", "ar")
+    # @return [Hash] paginated list of translations
+    def list_translations(language: nil, **params)
+      get("/translations/", { language: language }.merge(params))
+    end
+
+    # Get translation details by code (e.g. "sahih").
+    #
+    # @param code [String] translation code
+    # @return [Hash] translation details
+    def get_translation(code)
+      get("/translations/#{code}/")
+    end
+
+    # --- Ayahs ----------------------------------------------------------------
+
+    # List ayahs with optional filters.
+    #
+    # @param surah [String, nil] filter by surah slug
+    # @param translation [String, nil] filter by translation code
+    # @return [Hash] paginated list of ayahs
+    def list_ayahs(surah: nil, translation: nil, **params)
+      get("/ayahs/", { surah: surah, translation: translation }.merge(params))
+    end
+
+    # Get a specific ayah by its ID.
+    #
+    # @param ayah_id [Integer] ayah ID
+    # @return [Hash] ayah details
+    def get_ayah(ayah_id)
+      get("/ayahs/#{ayah_id}/")
+    end
+
+    # Search ayahs by text content.
+    #
+    # @param query [String] search query string
+    # @param surah [String, nil] restrict search to a specific surah slug
+    # @return [Hash] paginated search results
+    def search(query, surah: nil)
+      get("/ayahs/", { search: query, surah: surah })
+    end
+
+    # --- Juz & Hizb -----------------------------------------------------------
+
+    # List all 30 juz (parts) of the Quran.
+    #
+    # @return [Hash] paginated list of juz
+    def list_juz
+      get("/juz/")
+    end
+
+    # Get juz details by number (1-30).
+    #
+    # @param number [Integer] juz number
+    # @return [Hash] juz details
+    def get_juz(number)
+      get("/juz/#{number}/")
+    end
+
+    # List hizb (half-juz) markers.
+    #
+    # @param juz [Integer, nil] filter by juz number
+    # @return [Hash] paginated list of hizbs
+    def list_hizbs(juz: nil, **params)
+      get("/hizbs/", { juz: juz }.merge(params))
+    end
+
+    # Get hizb details by number.
+    #
+    # @param number [Integer] hizb number
+    # @return [Hash] hizb details
+    def get_hizb(number)
+      get("/hizbs/#{number}/")
+    end
+
+    # --- Tafsir ---------------------------------------------------------------
+
+    # List available tafsir (commentary) collections.
+    #
+    # @return [Hash] paginated list of tafsirs
+    def list_tafsirs
+      get("/tafsirs/")
+    end
+
+    # Get tafsir details by slug (e.g. "ibn-kathir").
+    #
+    # @param slug [String] tafsir slug
+    # @return [Hash] tafsir details
+    def get_tafsir(slug)
+      get("/tafsirs/#{slug}/")
+    end
+
+    # List tafsir entries with optional filters.
+    #
+    # @param tafsir [String, nil] filter by tafsir slug
+    # @param surah [String, nil] filter by surah slug
+    # @return [Hash] paginated list of tafsir entries
+    def list_tafsir_entries(tafsir: nil, surah: nil, **params)
+      get("/tafsir-entries/", { tafsir: tafsir, surah: surah }.merge(params))
+    end
+
+    # Get a specific tafsir entry by ID.
+    #
+    # @param entry_id [Integer] tafsir entry ID
+    # @return [Hash] tafsir entry details
+    def get_tafsir_entry(entry_id)
+      get("/tafsir-entries/#{entry_id}/")
+    end
+
+    # --- Hadith ---------------------------------------------------------------
+
+    # List hadith collections (Bukhari, Muslim, etc.).
+    #
+    # @return [Hash] paginated list of hadith collections
+    def list_hadith_collections
+      get("/hadith-collections/")
+    end
+
+    # Get hadith collection details by slug.
+    #
+    # @param slug [String] collection slug
+    # @return [Hash] collection details
+    def get_hadith_collection(slug)
+      get("/hadith-collections/#{slug}/")
+    end
+
+    # List hadiths with optional filters.
+    #
+    # @param collection [String, nil] filter by collection slug
+    # @param grade [String, nil] filter by grade (e.g. "sahih")
+    # @return [Hash] paginated list of hadiths
+    def list_hadiths(collection: nil, grade: nil, **params)
+      get("/hadiths/", { collection: collection, grade: grade }.merge(params))
+    end
+
+    # Get a specific hadith by ID.
+    #
+    # @param hadith_id [Integer] hadith ID
+    # @return [Hash] hadith details
+    def get_hadith(hadith_id)
+      get("/hadiths/#{hadith_id}/")
+    end
+
+    # Search hadith by text content.
+    #
+    # @param query [String] search query string
+    # @param collection [String, nil] restrict to a specific collection
+    # @return [Hash] paginated search results
+    def search_hadith(query, collection: nil)
+      get("/hadiths/", { search: query, collection: collection })
+    end
+
+    # --- People ---------------------------------------------------------------
+
+    # List Quranic people (prophets and figures).
+    #
+    # @param is_prophet [Boolean, nil] filter to prophets only
+    # @return [Hash] paginated list of people
+    def list_people(is_prophet: nil, **params)
+      get("/people/", { is_prophet: is_prophet }.merge(params))
+    end
+
+    # Get Quranic person details by slug.
+    #
+    # @param slug [String] person slug
+    # @return [Hash] person details
+    def get_person(slug)
+      get("/people/#{slug}/")
+    end
+
+    # --- Topics & Glossary ----------------------------------------------------
+
+    # List Quranic topics and themes.
+    #
+    # @return [Hash] paginated list of topics
+    def list_topics
+      get("/topics/")
+    end
+
+    # Get topic details by slug.
+    #
+    # @param slug [String] topic slug
+    # @return [Hash] topic details
+    def get_topic(slug)
+      get("/topics/#{slug}/")
+    end
+
+    # List Islamic glossary terms.
+    #
+    # @return [Hash] paginated list of glossary terms
+    def list_glossary
+      get("/glossary/")
+    end
+
+    # Get glossary term details by slug.
+    #
+    # @param slug [String] term slug
+    # @return [Hash] term details
+    def get_term(slug)
+      get("/glossary/#{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"] = "widequran-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/widequran/version.rb

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

data/lib/widequran.rb

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

metadata

@@ -0,0 +1,54 @@
+--- !ruby/object:Gem::Specification
+name: widequran
+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 widequran.com. Access 114 surahs, 6,236 ayahs, hadith
+  collections (Bukhari, Muslim), tafsir commentary (Ibn Kathir), juz/hizb divisions,
+  Quranic people, topics, and glossary. Zero dependencies.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/widequran.rb
+- lib/widequran/client.rb
+- lib/widequran/version.rb
+homepage: https://widequran.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://widequran.com
+  source_code_uri: https://github.com/dobestan/widequran-rb
+  changelog_uri: https://github.com/dobestan/widequran-rb/blob/main/CHANGELOG.md
+  documentation_uri: https://widequran.com/developers/
+  bug_tracker_uri: https://github.com/dobestan/widequran-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 WideQuran — Quran surahs, ayahs, hadith, tafsir commentary
+test_files: []