widesutra 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 656a4dec6e96f30b312cb9624982ac177e08a129e2bf91057cda30cba337da97
+  data.tar.gz: 1d94ff31e22863e5fafeaa79d4aba2ea4fde430d0f59a5f11ff05719ffb1066e
+SHA512:
+  metadata.gz: 6ec0836c0f913e1b3bf3a599225c62f835be09a6ba23dc3ddb3b997112835a199926e6c94b743a1222dea86f6551e1dabed13fed06d0b76fcc703a99155a7b49
+  data.tar.gz: 7e970e76c4c7a176003d66180e438ba813c0c0838e6b00015243104e5c8e312df1857cae31eee0e3fd2418ed2e6e405fd4aff4c1ccf5cbc5713d3d13e508ef59

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,233 @@
+# widesutra
+
+[![Gem Version](https://badge.fury.io/rb/widesutra.svg)](https://rubygems.org/gems/widesutra)
+[![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/widesutra)
+
+Ruby client for the [WideSutra](https://widesutra.com) API. Access Buddhist scripture collections (Tipitaka, Mahayana Sutras), individual books (Dhammapada, Heart Sutra, Diamond Sutra), texts with Pali and Sanskrit originals, multiple translations (Sujato, Thanissaro), Buddhist figures, core concepts (Four Noble Truths, Noble Eightfold Path), and a Pali/Sanskrit glossary. Zero runtime dependencies -- uses only Ruby stdlib (`net/http`, `json`, `uri`).
+
+WideSutra is a comprehensive Buddhist scripture encyclopedia providing structured access to the Theravada Pali Canon, Mahayana sutras, and the broader Buddhist intellectual tradition -- all accessible through a free REST API.
+
+> **Explore Buddhist scriptures at [widesutra.com](https://widesutra.com)** -- [Collections](https://widesutra.com/collections/), [Books](https://widesutra.com/books/), [Figures](https://widesutra.com/figures/), [Concepts](https://widesutra.com/concepts/), [Glossary](https://widesutra.com/glossary/)
+
+## Table of Contents
+
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [What You Can Do](#what-you-can-do)
+  - [Browse Scripture Collections](#browse-scripture-collections)
+  - [Read Books](#read-books)
+  - [Look Up Texts](#look-up-texts)
+  - [Search Scripture](#search-scripture)
+  - [Discover Buddhist Figures](#discover-buddhist-figures)
+  - [Explore Core Concepts](#explore-core-concepts)
+  - [Browse Topics and Glossary](#browse-topics-and-glossary)
+- [API Reference](#api-reference)
+- [Learn More About Buddhist Scripture](#learn-more-about-buddhist-scripture)
+- [WideHoly Scripture Family](#wideholy-scripture-family)
+- [Also Available](#also-available)
+- [License](#license)
+
+## Install
+
+```bash
+gem install widesutra
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "widesutra"
+```
+
+## Quick Start
+
+```ruby
+require "widesutra"
+
+# Create a client (zero configuration needed)
+client = WideSutra::Client.new
+
+# List scripture collections
+collections = client.list_collections
+puts collections["results"].first["name"]
+
+# Get a Dhammapada verse
+text = client.get_text("dhammapada", 1, 1)
+puts text["results"].first["text"]
+
+# Search across all Buddhist scriptures
+results = client.search("four noble truths")
+results["results"].each { |t| puts t["text"] }
+```
+
+## What You Can Do
+
+### Browse Scripture Collections
+
+Buddhist scriptures are organized into major collections by tradition. The Theravada tradition preserves the Tipitaka (Three Baskets): Vinaya Pitaka (monastic rules), Sutta Pitaka (discourses), and Abhidhamma Pitaka (philosophical analysis). Mahayana traditions add sutras like the Heart Sutra and Lotus Sutra.
+
+```ruby
+# List all collections
+collections = client.list_collections
+
+# Filter by tradition
+theravada = client.list_collections(tradition: "theravada")
+mahayana = client.list_collections(tradition: "mahayana")
+
+# Get details for the Tipitaka
+tipitaka = client.get_collection("tipitaka")
+```
+
+### Read Books
+
+Individual scriptures within the collections -- from the Dhammapada (verses of the Buddha) to the Heart Sutra (Prajnaparamita) and the Lotus Sutra (Saddharma Pundarika).
+
+```ruby
+# List all books
+books = client.list_books
+
+# Filter by collection
+sutta_pitaka = client.list_books(collection: "sutta-pitaka")
+
+# Get details for the Dhammapada
+dhammapada = client.get_book("dhammapada")
+puts dhammapada["name"]
+```
+
+### Look Up Texts
+
+Access individual verses and passages with Pali or Sanskrit originals alongside scholarly translations. Bhikkhu Sujato's translation is the default for Pali Canon texts.
+
+```ruby
+# Get a specific text passage
+text = client.get_text("dhammapada", 1, 1, translation: "sujato")
+
+# Use a different translation
+text = client.get_text("dhammapada", 1, 1, translation: "thanissaro")
+
+# Browse available translations
+translations = client.list_translations
+```
+
+### Search Scripture
+
+Full-text search across all Buddhist texts with relevance ranking.
+
+```ruby
+# Search across all scriptures
+results = client.search("suffering", limit: 10)
+results["results"].each do |text|
+  puts text["text"]
+end
+
+# Search for specific Buddhist concepts
+results = client.search("dependent origination")
+```
+
+### Discover Buddhist Figures
+
+Profiles of key figures in Buddhist history -- Siddhartha Gautama (the historical Buddha), bodhisattvas like Avalokiteshvara and Manjushri, and influential monks and scholars across Theravada and Mahayana traditions.
+
+```ruby
+# List all figures
+figures = client.list_figures
+
+# Filter by tradition
+theravada_figures = client.list_figures(tradition: "theravada")
+
+# Get the Buddha's profile
+buddha = client.get_figure("siddhartha-gautama")
+puts buddha["name"]
+```
+
+### Explore Core Concepts
+
+Central Buddhist doctrines and philosophical concepts -- the Four Noble Truths, Noble Eightfold Path, Three Marks of Existence, Dependent Origination, and more.
+
+| Concept | Pali/Sanskrit | Description |
+|---------|---------------|-------------|
+| Four Noble Truths | Cattari Ariyasaccani | Suffering, origin, cessation, path |
+| Noble Eightfold Path | Ariya Atthangika Magga | Right view through right concentration |
+| Three Marks | Tilakkhana | Impermanence, suffering, non-self |
+| Dependent Origination | Paticca Samuppada | 12-link chain of causation |
+| Five Aggregates | Panca Khandha | Form, feeling, perception, formations, consciousness |
+
+```ruby
+# List concepts
+concepts = client.list_concepts
+
+# Filter by category
+meditation = client.list_concepts(category: "meditation")
+
+# Get the Four Noble Truths
+fnt = client.get_concept("four-noble-truths")
+puts fnt["description"]
+```
+
+### Browse Topics and Glossary
+
+Thematic verse collections and a Pali/Sanskrit glossary with definitions, etymology, and usage contexts.
+
+```ruby
+# Browse topics
+topics = client.list_topics
+topic = client.get_topic("compassion")
+
+# Browse glossary
+terms = client.list_glossary
+term = client.get_glossary_term("nibbana")
+puts term["definition"]
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `list_collections(tradition:)` | List scripture collections |
+| `get_collection(slug)` | Get collection details |
+| `list_books(collection:)` | List books in collections |
+| `get_book(slug)` | Get book details |
+| `get_text(book, chapter, verse, translation:)` | Get a specific text |
+| `search(query, limit:)` | Search scripture texts |
+| `list_translations` | List available translations |
+| `get_translation(code)` | Get translation details |
+| `list_figures(tradition:)` | List Buddhist figures |
+| `get_figure(slug)` | Get figure details |
+| `list_concepts(category:)` | List Buddhist concepts |
+| `get_concept(slug)` | Get concept details |
+| `list_topics` | List topics and themes |
+| `get_topic(slug)` | Get topic details |
+| `list_glossary` | List Pali/Sanskrit glossary |
+| `get_glossary_term(slug)` | Get term definition |
+
+## Learn More About Buddhist Scripture
+
+- **Browse**: [Collections](https://widesutra.com/collections/) -- [Books](https://widesutra.com/books/) -- [Figures](https://widesutra.com/figures/)
+- **Study**: [Concepts](https://widesutra.com/concepts/) -- [Topics](https://widesutra.com/topics/) -- [Glossary](https://widesutra.com/glossary/)
+- **API**: [REST API Docs](https://widesutra.com/developers/) -- [OpenAPI Spec](https://widesutra.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 widesutra` | [PyPI](https://pypi.org/project/widesutra/) |
+| **npm** | `npm install widesutra` | [npm](https://www.npmjs.com/package/widesutra) |
+
+## License
+
+MIT

data/lib/widesutra/client.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module WideSutra
+  # HTTP client for the WideSutra REST API.
+  #
+  # Zero runtime dependencies -- uses only Ruby stdlib (net/http, json, uri).
+  #
+  #   client = WideSutra::Client.new
+  #   collections = client.list_collections
+  #   text = client.get_text("dhammapada", 1, 1)
+  #   results = client.search("four noble truths")
+  #
+  class Client
+    DEFAULT_BASE_URL = "https://widesutra.com/api/v1/sutra"
+    DEFAULT_TIMEOUT  = 10
+
+    def initialize(base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+    end
+
+    # --- Collections ----------------------------------------------------------
+
+    # List scripture collections (Tipitaka, Mahayana Sutras, etc.).
+    #
+    # @param tradition [String, nil] filter by tradition ("theravada", "mahayana")
+    # @return [Hash] paginated list of collections
+    def list_collections(tradition: nil, **params)
+      get("/collections/", { tradition: tradition }.merge(params))
+    end
+
+    # Get collection details by slug (e.g. "tipitaka").
+    #
+    # @param slug [String] collection URL slug
+    # @return [Hash] collection details
+    def get_collection(slug)
+      get("/collections/#{slug}/")
+    end
+
+    # --- Books ----------------------------------------------------------------
+
+    # List books within scripture collections.
+    #
+    # @param collection [String, nil] filter by collection slug
+    # @return [Hash] paginated list of books
+    def list_books(collection: nil, **params)
+      get("/books/", { collection__slug: collection }.merge(params))
+    end
+
+    # Get book details by slug (e.g. "dhammapada", "heart-sutra").
+    #
+    # @param slug [String] book URL slug
+    # @return [Hash] book details
+    def get_book(slug)
+      get("/books/#{slug}/")
+    end
+
+    # --- Texts ----------------------------------------------------------------
+
+    # Get a specific scripture text by book, chapter, and verse number.
+    #
+    # @param book [String] book slug (e.g. "dhammapada")
+    # @param chapter [Integer] chapter number
+    # @param verse [Integer] verse number within the chapter
+    # @param translation [String] translation code (default: "sujato")
+    # @return [Hash] text data with Pali/Sanskrit and translation
+    def get_text(book, chapter, verse, translation: "sujato")
+      get("/texts/", {
+        chapter__book__slug: book,
+        chapter__number: chapter,
+        number: verse,
+        translation__code: translation
+      })
+    end
+
+    # Search scripture texts 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("/texts/", { search: query, page_size: limit })
+    end
+
+    # --- Translations ---------------------------------------------------------
+
+    # List available text translations (Sujato, Thanissaro, etc.).
+    #
+    # @return [Hash] paginated list of translations
+    def list_translations(**params)
+      get("/translations/", params)
+    end
+
+    # Get translation details by code (e.g. "sujato").
+    #
+    # @param code [String] translation code
+    # @return [Hash] translation details
+    def get_translation(code)
+      get("/translations/#{code}/")
+    end
+
+    # --- Figures --------------------------------------------------------------
+
+    # List Buddhist figures (Buddhas, bodhisattvas, monks).
+    #
+    # @param tradition [String, nil] filter by tradition ("theravada", "mahayana")
+    # @return [Hash] paginated list of figures
+    def list_figures(tradition: nil, **params)
+      get("/figures/", { tradition: tradition }.merge(params))
+    end
+
+    # Get figure details by slug (e.g. "siddhartha-gautama").
+    #
+    # @param slug [String] figure URL slug
+    # @return [Hash] figure details
+    def get_figure(slug)
+      get("/figures/#{slug}/")
+    end
+
+    # --- Concepts -------------------------------------------------------------
+
+    # List Buddhist concepts (Four Noble Truths, Noble Eightfold Path, etc.).
+    #
+    # @param category [String, nil] filter by category
+    # @return [Hash] paginated list of concepts
+    def list_concepts(category: nil, **params)
+      get("/concepts/", { category: category }.merge(params))
+    end
+
+    # Get concept details by slug (e.g. "four-noble-truths").
+    #
+    # @param slug [String] concept URL slug
+    # @return [Hash] concept details
+    def get_concept(slug)
+      get("/concepts/#{slug}/")
+    end
+
+    # --- Topics ---------------------------------------------------------------
+
+    # List Buddhist topics and themes.
+    #
+    # @return [Hash] paginated list of topics
+    def list_topics(**params)
+      get("/topics/", params)
+    end
+
+    # Get topic details by slug.
+    #
+    # @param slug [String] topic URL slug
+    # @return [Hash] topic details
+    def get_topic(slug)
+      get("/topics/#{slug}/")
+    end
+
+    # --- Glossary -------------------------------------------------------------
+
+    # List Pali and Sanskrit glossary terms.
+    #
+    # @return [Hash] paginated list of glossary terms
+    def list_glossary(**params)
+      get("/glossary/", params)
+    end
+
+    # Get glossary term details by slug.
+    #
+    # @param slug [String] term URL slug
+    # @return [Hash] glossary term details
+    def get_glossary_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"] = "widesutra-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/widesutra/version.rb

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

data/lib/widesutra.rb

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

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: widesutra
+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 widesutra.com. Access Buddhist scripture collections (Tipitaka,
+  Mahayana Sutras), books, texts with Pali/Sanskrit originals and translations, Buddhist
+  figures, concepts (Four Noble Truths, Noble Eightfold Path), topics, and Pali/Sanskrit
+  glossary. Zero dependencies.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/widesutra.rb
+- lib/widesutra/client.rb
+- lib/widesutra/version.rb
+homepage: https://widesutra.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://widesutra.com
+  source_code_uri: https://github.com/dobestan/widesutra-rb
+  changelog_uri: https://github.com/dobestan/widesutra-rb/blob/main/CHANGELOG.md
+  documentation_uri: https://widesutra.com/developers/
+  bug_tracker_uri: https://github.com/dobestan/widesutra-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 WideSutra — Buddhist scriptures, Tipitaka, Pali Canon
+test_files: []