astroapi-ruby 1.0.0

data/lib/astroapi/categories/tarot.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+require_relative 'base_category'
+require_relative '../validators/subject_validator'
+
+module Astroapi
+  module Categories
+    # Tarot category client for tarot readings and analysis
+    class Tarot < BaseCategory
+      # Get cards glossary
+      # @param params [Hash] Query parameters
+      # @return [Hash] 78 cards reference
+      def get_cards_glossary(params = {})
+        http.get(build_url('glossary', 'cards'), params: params)
+      end
+
+      # Get spreads glossary
+      # @param params [Hash] Query parameters
+      # @return [Hash] Spread types
+      def get_spreads_glossary(params = {})
+        http.get(build_url('glossary', 'spreads'), params: params)
+      end
+
+      # Get card details
+      # @param card_id [String] Card ID
+      # @return [Hash] Card details
+      def get_card_details(card_id)
+        http.get(build_url('glossary', 'cards', card_id))
+      end
+
+      # Draw cards
+      # @param request [Hash] Number of cards and options
+      # @return [Hash] Random card draw
+      def draw_cards(request)
+        http.post(build_url('cards', 'draw'), body: request)
+      end
+
+      # Search cards
+      # @param params [Hash] Search keywords
+      # @return [Hash] Matching cards
+      def search_cards(params = {})
+        http.get(build_url('cards', 'search'), params: params)
+      end
+
+      # Get daily card
+      # @param params [Hash] Query parameters
+      # @return [Hash] Daily card
+      def get_daily_card(params = {})
+        http.get(build_url('cards', 'daily'), params: params)
+      end
+
+      # Generate single card report
+      # @param request [Hash] Card and question
+      # @return [Hash] Single card reading
+      def generate_single_report(request)
+        http.post(build_url('reports', 'single'), body: request)
+      end
+
+      # Generate three card report
+      # @param request [Hash] Three cards
+      # @return [Hash] Past/present/future reading
+      def generate_three_card_report(request)
+        http.post(build_url('reports', 'three-card'), body: request)
+      end
+
+      # Generate Celtic Cross report
+      # @param request [Hash] Ten cards
+      # @return [Hash] 10-card spread
+      def generate_celtic_cross_report(request)
+        http.post(build_url('reports', 'celtic-cross'), body: request)
+      end
+
+      # Generate synastry report
+      # @param request [Hash] Cards and two subjects
+      # @return [Hash] Relationship reading
+      def generate_synastry_report(request)
+        http.post(build_url('reports', 'synastry'), body: request)
+      end
+
+      # Generate houses report
+      # @param request [Hash] Cards for 12 houses
+      # @return [Hash] 12-house spread
+      def generate_houses_report(request)
+        http.post(build_url('reports', 'houses'), body: request)
+      end
+
+      # Generate Tree of Life report
+      # @param request [Hash] Cards for Kabbalah spread
+      # @return [Hash] Tree of Life spread
+      def generate_tree_of_life_report(request)
+        http.post(build_url('reports', 'tree-of-life'), body: request)
+      end
+
+      # Calculate quintessence
+      # @param request [Hash] Cards for synthesis
+      # @return [Hash] Synthesis card
+      def calculate_quintessence(request)
+        http.post(build_url('analysis', 'quintessence'), body: request)
+      end
+
+      # Calculate birth cards
+      # @param request [Hash] Birth date
+      # @return [Hash] Personality/soul cards
+      def calculate_birth_cards(request)
+        http.post(build_url('analysis', 'birth-cards'), body: request)
+      end
+
+      # Calculate elemental dignities
+      # @param request [Hash] Cards for analysis
+      # @return [Hash] Elemental interactions
+      def calculate_elemental_dignities(request)
+        http.post(build_url('analysis', 'dignities'), body: request)
+      end
+
+      # Analyze timing
+      # @param request [Hash] Cards and question
+      # @return [Hash] Timing implications
+      def analyze_timing(request)
+        http.post(build_url('analysis', 'timing'), body: request)
+      end
+
+      # Calculate optimal times
+      # @param request [Hash] Cards and date range
+      # @return [Hash] Best timing windows
+      def calculate_optimal_times(request)
+        http.post(build_url('analysis', 'optimal-times'), body: request)
+      end
+
+      # Generate transit report
+      # @param request [Hash] Birth data and cards
+      # @return [Hash] Astro-tarot transit
+      def generate_transit_report(request)
+        if request[:subject] || request['subject']
+          Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        end
+        http.post(build_url('analysis', 'transit-report'), body: request)
+      end
+
+      # Generate natal report
+      # @param request [Hash] Birth data and cards
+      # @return [Hash] Astro-tarot natal
+      def generate_natal_report(request)
+        if request[:subject] || request['subject']
+          Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        end
+        http.post(build_url('analysis', 'natal-report'), body: request)
+      end
+
+      protected
+
+      def api_prefix
+        '/api/v3/tarot'
+      end
+    end
+  end
+end

data/lib/astroapi/categories/traditional.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative 'base_category'
+require_relative '../validators/subject_validator'
+
+module Astroapi
+  module Categories
+    # Traditional astrology category client
+    class Traditional < BaseCategory
+      # Get traditional analysis
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Comprehensive traditional analysis
+      def get_analysis(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('analysis'), body: request)
+      end
+
+      # Get dignities analysis
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Essential dignities
+      def get_dignities_analysis(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('dignities'), body: request)
+      end
+
+      # Get lots analysis
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Arabic/Hellenistic lots
+      def get_lots_analysis(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('lots'), body: request)
+      end
+
+      # Get profections analysis
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Profections analysis
+      def get_profections_analysis(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('profections'), body: request)
+      end
+
+      # Get annual profection
+      # @param request [Hash] Subject and specific year
+      # @return [Hash] Profection for year
+      def get_annual_profection(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('analysis', 'annual-profection'), body: request)
+      end
+
+      # Get profection timeline
+      # @param request [Hash] Subject and year range
+      # @return [Hash] Multi-year timeline
+      def get_profection_timeline(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('analysis', 'profection-timeline'), body: request)
+      end
+
+      # Get traditional points glossary
+      # @param params [Hash] Query parameters
+      # @return [Hash] Traditional points reference
+      def get_traditional_points_glossary(params = {})
+        http.get(build_url('glossary', 'traditional-points'), params: params)
+      end
+
+      # Get dignities glossary
+      # @param params [Hash] Query parameters
+      # @return [Hash] Dignities reference
+      def get_dignities_glossary(params = {})
+        http.get(build_url('glossary', 'dignities'), params: params)
+      end
+
+      # Get profection houses glossary
+      # @param params [Hash] Query parameters
+      # @return [Hash] Profection houses reference
+      def get_profection_houses_glossary(params = {})
+        http.get(build_url('glossary', 'profection-houses'), params: params)
+      end
+
+      # Get capabilities
+      # @param params [Hash] Query parameters
+      # @return [Hash] Available features
+      def get_capabilities(params = {})
+        http.get(build_url('capabilities'), params: params)
+      end
+
+      protected
+
+      def api_prefix
+        '/api/v3/traditional'
+      end
+    end
+  end
+end

data/lib/astroapi/categories/vedic.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require_relative 'base_category'
+require_relative '../validators/subject_validator'
+
+module Astroapi
+  module Categories
+    # Vedic astrology category client
+    class Vedic < BaseCategory
+      # Get Vedic birth details
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Vedic birth details
+      def get_birth_details(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('birth-details'), body: request)
+      end
+
+      # Generate Vedic chart SVG
+      # @param request [Hash] Subject birth data and options
+      # @return [Hash] Vedic chart SVG
+      def get_chart(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('chart'), body: request)
+      end
+
+      # Render Vedic chart in specified format
+      # @param format [String] Output format (png, svg, etc.)
+      # @param request [Hash] Subject birth data and options
+      # @return [Hash] Rendered chart
+      def render_chart(format, request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('chart', 'render', format), body: request)
+      end
+
+      # Get divisional charts
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Divisional chart data
+      def get_divisional_chart(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('divisional-chart'), body: request)
+      end
+
+      # Get Panchang
+      # @param request [Hash] Date and location
+      # @return [Hash] Daily Panchang
+      def get_panchang(request)
+        http.post(build_url('panchang'), body: request)
+      end
+
+      # Get regional Panchang
+      # @param request [Hash] Date, location, and region
+      # @return [Hash] Regional Panchang
+      def get_regional_panchang(request)
+        http.post(build_url('regional-panchang'), body: request)
+      end
+
+      # Calculate Ashtakvarga
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Ashtakvarga strength analysis
+      def calculate_ashtakvarga(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('ashtakvarga'), body: request)
+      end
+
+      # Calculate Shadbala
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Six-fold strength analysis
+      def calculate_shadbala(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('shadbala'), body: request)
+      end
+
+      # Get Vimshottari Dasha
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Dasha periods
+      def get_vimshottari_dasha(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('vimshottari-dasha'), body: request)
+      end
+
+      # Get Yogini Dasha
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Yogini Dasha periods
+      def get_yogini_dasha(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('yogini-dasha'), body: request)
+      end
+
+      # Calculate Chara Dasha
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Chara Dasha periods
+      def calculate_chara_dasha(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('chara-dasha'), body: request)
+      end
+
+      # Analyze yogas
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Yoga analysis
+      def analyze_yogas(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('yoga-analysis'), body: request)
+      end
+
+      # Get Nakshatra predictions
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Nakshatra predictions
+      def get_nakshatra_predictions(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('nakshatra-predictions'), body: request)
+      end
+
+      # Get Manglik Dosha
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Manglik analysis
+      def get_manglik_dosha(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('manglik-dosha'), body: request)
+      end
+
+      # Get Kaal Sarpa Dosha
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Kaal Sarpa analysis
+      def get_kaal_sarpa_dosha(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('kaal-sarpa-dosha'), body: request)
+      end
+
+      # Get Sade Sati
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Sade Sati analysis
+      def get_sade_sati(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('sade-sati'), body: request)
+      end
+
+      # Get Kundli matching
+      # @param request [Hash] Two subjects' birth data
+      # @return [Hash] Kundli matching results
+      def get_kundli_matching(request)
+        http.post(build_url('kundli-matching'), body: request)
+      end
+
+      # Get Vedic transit
+      # @param request [Hash] Subject and transit date
+      # @return [Hash] Vedic transit data
+      def get_transit(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('transit'), body: request)
+      end
+
+      # Calculate Varshaphal
+      # @param request [Hash] Subject and year
+      # @return [Hash] Annual horoscope
+      def calculate_varshaphal(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('varshaphal'), body: request)
+      end
+
+      # Get remedies
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Suggested remedies
+      def get_remedies(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('remedies'), body: request)
+      end
+
+      # Get festival calendar
+      # @param request [Hash] Date range and location
+      # @return [Hash] Hindu festival calendar
+      def get_festival_calendar(request)
+        http.post(build_url('festival-calendar'), body: request)
+      end
+
+      # Calculate KP system
+      # @param request [Hash] Subject birth data
+      # @return [Hash] KP system analysis
+      def calculate_kp_system(request)
+        Validators::SubjectValidator.validate!(request[:subject] || request['subject'])
+        http.post(build_url('kp-system'), body: request)
+      end
+
+      protected
+
+      def api_prefix
+        '/api/v3/vedic'
+      end
+    end
+  end
+end

data/lib/astroapi/categories/ziwei.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative 'base_category'
+require_relative '../validators/subject_validator'
+
+module Astroapi
+  module Categories
+    # Zi Wei Dou Shu (Purple Star) category client
+    class Ziwei < BaseCategory
+      # Calculate Zi Wei chart
+      # @param request [Hash] Subject birth data
+      # @return [Hash] Zi Wei Dou Shu chart
+      def calculate_chart(request)
+        Validators::SubjectValidator.validate!(request)
+        http.post(build_url('chart'), body: request)
+      end
+
+      protected
+
+      def api_prefix
+        '/api/v3/ziwei'
+      end
+    end
+  end
+end

data/lib/astroapi/client.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative 'configuration'
+require_relative 'http/client'
+require_relative 'categories/data'
+require_relative 'categories/charts'
+require_relative 'categories/horoscope'
+require_relative 'categories/analysis'
+require_relative 'categories/glossary'
+require_relative 'categories/astrocartography'
+require_relative 'categories/chinese'
+require_relative 'categories/eclipses'
+require_relative 'categories/lunar'
+require_relative 'categories/numerology'
+require_relative 'categories/tarot'
+require_relative 'categories/traditional'
+require_relative 'categories/fixed_stars'
+require_relative 'categories/insights'
+require_relative 'categories/svg'
+require_relative 'categories/enhanced'
+require_relative 'categories/vedic'
+require_relative 'categories/human_design'
+require_relative 'categories/kabbalah'
+require_relative 'categories/horary'
+require_relative 'categories/fengshui'
+require_relative 'categories/palmistry'
+require_relative 'categories/pdf'
+require_relative 'categories/render'
+require_relative 'categories/ziwei'
+
+module Astroapi
+  # Main client for the Astrology API
+  #
+  # @example Initialize with API key
+  #   client = Astroapi::Client.new(api_key: 'your-api-key')
+  #
+  # @example Initialize with configuration block
+  #   client = Astroapi::Client.new do |config|
+  #     config.api_key = 'your-api-key'
+  #     config.timeout = 15
+  #     config.debug = true
+  #   end
+  #
+  # @example Use environment variables
+  #   ENV['ASTROLOGY_API_KEY'] = 'your-api-key'
+  #   client = Astroapi::Client.new
+  class Client
+    attr_reader :data, :charts, :horoscope, :analysis, :glossary,
+                :astrocartography, :chinese, :eclipses, :lunar, :numerology,
+                :tarot, :traditional, :fixed_stars, :insights, :svg, :enhanced,
+                :vedic, :human_design, :kabbalah, :horary, :fengshui,
+                :palmistry, :pdf, :render, :ziwei,
+                :config
+
+    # Initialize a new client
+    # @param options [Hash] Configuration options
+    # @option options [String] :api_key API key for authentication
+    # @option options [String] :base_url Base URL for the API
+    # @option options [Integer] :timeout Request timeout in seconds
+    # @option options [Boolean] :debug Enable debug logging
+    # @yield [config] Configuration block
+    # @yieldparam config [Configuration] Configuration object
+    def initialize(options = {})
+      @config = Configuration.new
+
+      if block_given?
+        yield @config
+      else
+        options.each do |key, value|
+          @config.public_send(:"#{key}=", value) if @config.respond_to?(:"#{key}=")
+        end
+      end
+
+      @http_client = HTTP::Client.new(@config)
+
+      @data = Categories::Data.new(@http_client)
+      @charts = Categories::Charts.new(@http_client)
+      @horoscope = Categories::Horoscope.new(@http_client)
+      @analysis = Categories::Analysis.new(@http_client)
+      @glossary = Categories::Glossary.new(@http_client)
+      @astrocartography = Categories::Astrocartography.new(@http_client)
+      @chinese = Categories::Chinese.new(@http_client)
+      @eclipses = Categories::Eclipses.new(@http_client)
+      @lunar = Categories::Lunar.new(@http_client)
+      @numerology = Categories::Numerology.new(@http_client)
+      @tarot = Categories::Tarot.new(@http_client)
+      @traditional = Categories::Traditional.new(@http_client)
+      @fixed_stars = Categories::FixedStars.new(@http_client)
+      @insights = Categories::InsightsCategory.new(@http_client)
+      @svg = Categories::Svg.new(@http_client)
+      @enhanced = Categories::Enhanced.new(@http_client)
+      @vedic = Categories::Vedic.new(@http_client)
+      @human_design = Categories::HumanDesign.new(@http_client)
+      @kabbalah = Categories::Kabbalah.new(@http_client)
+      @horary = Categories::Horary.new(@http_client)
+      @fengshui = Categories::Fengshui.new(@http_client)
+      @palmistry = Categories::Palmistry.new(@http_client)
+      @pdf = Categories::Pdf.new(@http_client)
+      @render = Categories::Render.new(@http_client)
+      @ziwei = Categories::Ziwei.new(@http_client)
+    end
+  end
+end

data/lib/astroapi/configuration.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module Astroapi
+  # Configuration for the Astroapi client
+  class Configuration
+    DEFAULT_BASE_URL = 'https://api.astrology-api.io'
+    DEFAULT_TIMEOUT = 10
+    DEFAULT_RETRY_STATUS_CODES = [408, 425, 429, 500, 502, 503, 504].freeze
+
+    attr_accessor :api_key, :base_url, :timeout, :debug, :logger
+    attr_reader :retry
+
+    def initialize
+      @api_key = ENV.fetch('ASTROLOGY_API_KEY', nil)
+      @base_url = ENV.fetch('ASTROLOGY_API_BASE_URL', DEFAULT_BASE_URL)
+      @timeout = DEFAULT_TIMEOUT
+      @debug = parse_boolean(ENV.fetch('ASTROLOGY_DEBUG', nil))
+      @logger = Logger.new($stdout)
+      @logger.level = Logger::INFO
+      @retry = RetryConfig.new
+    end
+
+    # Retry configuration
+    class RetryConfig
+      attr_accessor :attempts, :delay_ms, :retry_status_codes
+
+      def initialize
+        @attempts = 0
+        @delay_ms = 250
+        @retry_status_codes = DEFAULT_RETRY_STATUS_CODES.dup
+      end
+    end
+
+    private
+
+    def parse_boolean(value)
+      return false if value.nil? || value.empty?
+
+      %w[true 1 yes on].include?(value.to_s.downcase)
+    end
+  end
+end

data/lib/astroapi/error.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Astroapi
+  # Base error class for all Astroapi errors
+  class Error < StandardError
+    attr_reader :status_code, :code, :details, :response
+
+    def initialize(message, status_code: nil, code: nil, details: nil, response: nil)
+      super(message)
+      @status_code = status_code
+      @code = code
+      @details = details
+      @response = response
+    end
+
+    # Check if error is a client error (4xx)
+    # @return [Boolean]
+    def client_error?
+      return false unless status_code
+
+      status_code >= 400 && status_code < 500
+    end
+
+    # Check if error is a server error (5xx)
+    # @return [Boolean]
+    def server_error?
+      return false unless status_code
+
+      status_code >= 500 && status_code < 600
+    end
+
+    # Convert a Faraday error to an Astroapi error
+    # @param error [Faraday::Error] The Faraday error
+    # @return [Astroapi::Error] Normalized error
+    def self.from_faraday_error(error)
+      case error
+      when Faraday::TimeoutError
+        TimeoutError.new(error.message, details: error)
+      when Faraday::ConnectionFailed
+        ConnectionError.new(error.message, details: error)
+      when Faraday::ServerError
+        status = error.response&.dig(:status)
+        body = error.response&.dig(:body)
+        ServerError.new(error.message, status_code: status, response: body, details: error)
+      when Faraday::ClientError
+        status = error.response&.dig(:status)
+        body = error.response&.dig(:body)
+        ClientError.new(error.message, status_code: status, response: body, details: error)
+      else
+        status = error.respond_to?(:response) ? error.response&.dig(:status) : nil
+        body = error.respond_to?(:response) ? error.response&.dig(:body) : nil
+        new(error.message, status_code: status, response: body, details: error)
+      end
+    end
+  end
+
+  # Client error (4xx)
+  class ClientError < Error; end
+
+  # Server error (5xx)
+  class ServerError < Error; end
+
+  # Timeout error
+  class TimeoutError < Error; end
+
+  # Connection error
+  class ConnectionError < Error; end
+
+  # Validation error
+  class ValidationError < Error; end
+
+  # Configuration error
+  class ConfigurationError < Error; end
+end