moon_phase_tracker 1.3.2

data/examples/eight_phases_example.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add the lib directory to the load path
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'moon_phase_tracker'
+
+puts '=== Moon Phase Tracker - 8 Phases Example ==='
+puts 'Demonstrating all 8 lunar phases (4 major + 4 intermediate)'
+puts ''
+
+begin
+  # Example 1: Get all 8 phases for August 2025
+  puts '🌙 All phases for August 2025:'
+  puts '=' * 40
+  phases = MoonPhaseTracker.all_phases_for_month(2025, 8)
+
+  if phases.any?
+    phases.each do |phase|
+      prefix = phase.interpolated ? '~ ' : '  '
+      puts "#{prefix}#{phase}"
+    end
+
+    major_count = phases.count { |p| !p.interpolated }
+    interpolated_count = phases.count(&:interpolated)
+
+    puts ''
+    puts "Total: #{phases.size} phases (#{major_count} major, #{interpolated_count} interpolated)"
+    puts '~ indicates interpolated phases'
+  else
+    puts 'No phases found for this period.'
+  end
+
+  puts ''
+  puts '-' * 50
+  puts ''
+
+  # Example 2: Compare 4 vs 8 phases
+  puts '🔍 Comparison: 4 Major Phases vs 8 Complete Phases'
+  puts '=' * 55
+
+  major_phases = MoonPhaseTracker.phases_for_month(2025, 8)
+  all_phases = MoonPhaseTracker.all_phases_for_month(2025, 8)
+
+  puts "Major phases only (#{major_phases.size}):"
+  major_phases.each { |phase| puts "  #{phase}" }
+
+  puts ''
+  puts "All phases including interpolated (#{all_phases.size}):"
+  all_phases.each do |phase|
+    prefix = phase.interpolated ? '~ ' : '  '
+    puts "#{prefix}#{phase}"
+  end
+
+  puts ''
+  puts '-' * 50
+  puts ''
+
+  # Example 3: Show phase symbols
+  puts '🎭 Phase Symbols Reference'
+  puts '=' * 30
+  MoonPhaseTracker::Phase::PHASE_SYMBOLS.each do |type, symbol|
+    name = type.to_s.split('_').map(&:capitalize).join(' ')
+    puts "#{symbol} #{name}"
+  end
+
+  puts ''
+  puts '-' * 50
+  puts ''
+
+  # Example 4: Get phases from a specific date with 8 phases
+  puts '📅 8 Phases from a specific date (2025-08-01, 2 cycles)'
+  puts '=' * 60
+  date_phases = MoonPhaseTracker.all_phases_from_date('2025-08-01', 2)
+
+  if date_phases.any?
+    date_phases.each do |phase|
+      prefix = phase.interpolated ? '~ ' : '  '
+      puts "#{prefix}#{phase}"
+    end
+
+    major_count = date_phases.count { |p| !p.interpolated }
+    interpolated_count = date_phases.count(&:interpolated)
+
+    puts ''
+    puts "Total: #{date_phases.size} phases over 2 lunar cycles"
+    puts "(#{major_count} major, #{interpolated_count} interpolated)"
+  end
+rescue MoonPhaseTracker::Error => e
+  puts "Error: #{e.message}"
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+  puts 'This example requires an active internet connection to fetch moon phase data.'
+end
+
+puts ''
+puts 'Note: This example uses real astronomical data from the US Naval Observatory.'
+puts 'Interpolated phases (~) are calculated estimates between official phases.'
+puts 'All dates are in ISO 8601 format (YYYY-MM-DD) and times are in UTC.'

data/examples/rate_limiting_example.rb

@@ -0,0 +1,117 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example demonstrating rate limiting functionality in MoonPhaseTracker
+# This example shows different ways to configure and use rate limiting
+
+require_relative "../lib/moon_phase_tracker"
+
+puts "=== MoonPhaseTracker Rate Limiting Examples ==="
+puts
+
+puts "1. Default Rate Limiting (1 request/second):"
+puts "=" * 50
+
+tracker = MoonPhaseTracker::Tracker.new
+puts "Rate limit configuration: #{tracker.rate_limit_info}"
+
+start_time = Time.now
+puts "Making first request..."
+phases1 = tracker.phases_for_year(2025)
+first_request_time = Time.now - start_time
+
+puts "Making second request (should be rate limited)..."
+phases2 = tracker.phases_for_year(2024)
+total_time = Time.now - start_time
+
+puts "First request took: #{first_request_time.round(2)}s"
+puts "Total time for both requests: #{total_time.round(2)}s"
+puts "Rate limiting delay: #{(total_time - first_request_time).round(2)}s"
+puts
+
+puts "2. Custom Rate Limiting (3 requests/second, burst size 2):"
+puts "=" * 55
+
+custom_rate_limiter = MoonPhaseTracker::RateLimiter.new(
+  requests_per_second: 3.0,
+  burst_size: 2
+)
+
+custom_tracker = MoonPhaseTracker::Tracker.new(rate_limiter: custom_rate_limiter)
+puts "Rate limit configuration: #{custom_tracker.rate_limit_info}"
+
+start_time = Time.now
+puts "Making burst requests (should be immediate)..."
+custom_tracker.phases_for_year(2025)
+custom_tracker.phases_for_year(2024)
+burst_time = Time.now - start_time
+
+puts "Making third request (should be rate limited)..."
+custom_tracker.phases_for_year(2023)
+total_time = Time.now - start_time
+
+puts "Burst requests (2) took: #{burst_time.round(2)}s"
+puts "Total time for 3 requests: #{total_time.round(2)}s"
+puts "Rate limiting delay for 3rd request: #{(total_time - burst_time).round(2)}s"
+puts
+
+puts "3. Environment Variable Configuration:"
+puts "=" * 42
+
+ENV["MOON_PHASE_RATE_LIMIT"] = "2.5"
+ENV["MOON_PHASE_BURST_SIZE"] = "3"
+
+env_tracker = MoonPhaseTracker::Tracker.new
+puts "Rate limit configuration from ENV: #{env_tracker.rate_limit_info}"
+puts
+
+puts "4. Disabled Rate Limiting:"
+puts "=" * 27
+
+ENV["MOON_PHASE_RATE_LIMIT"] = "0"
+
+disabled_tracker = MoonPhaseTracker::Tracker.new
+puts "Rate limit configuration: #{disabled_tracker.rate_limit_info || 'DISABLED'}"
+
+start_time = Time.now
+puts "Making multiple requests without rate limiting..."
+5.times do |i|
+  disabled_tracker.phases_for_year(2025 - i)
+end
+total_time = Time.now - start_time
+
+puts "5 requests took: #{total_time.round(2)}s (no rate limiting)"
+puts
+
+puts "5. Rate Limit Status Monitoring:"
+puts "=" * 34
+
+rate_limiter = MoonPhaseTracker::RateLimiter.new(
+  requests_per_second: 1.0,
+  burst_size: 2
+)
+
+puts "Initial status: #{rate_limiter.configuration}"
+puts "Can proceed? #{rate_limiter.can_proceed?}"
+
+puts "\nMaking first request..."
+rate_limiter.throttle
+puts "After 1st request: #{rate_limiter.configuration}"
+puts "Can proceed? #{rate_limiter.can_proceed?}"
+
+puts "\nMaking second request..."
+rate_limiter.throttle
+puts "After 2nd request: #{rate_limiter.configuration}"
+puts "Can proceed? #{rate_limiter.can_proceed?}"
+
+puts "\nWaiting for token replenishment..."
+sleep(1.1)
+puts "After waiting: #{rate_limiter.configuration}"
+puts "Can proceed? #{rate_limiter.can_proceed?}"
+
+puts
+puts "=== Rate Limiting Examples Complete ==="
+
+# Clean up environment variables
+ENV.delete("MOON_PHASE_RATE_LIMIT")
+ENV.delete("MOON_PHASE_BURST_SIZE")

data/examples/usage_example.rb

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/moon_phase_tracker'
+
+puts '=== Moon Phase Tracker - Usage Examples =='
+puts
+
+tracker = MoonPhaseTracker::Tracker.new
+
+begin
+  puts '1. Moon phases for August 2025:'
+  puts '-' * 40
+  august_phases = MoonPhaseTracker.phases_for_month(2025, 8)
+  puts tracker.format_phases(august_phases, "#{MoonPhaseTracker::Tracker.month_name(8)} 2025 Phases")
+  puts
+
+  puts '2. All moon phases in 2025 (first 8):'
+  puts '-' * 50
+  year_phases = MoonPhaseTracker.phases_for_year(2025)
+  puts tracker.format_phases(year_phases.first(8), 'First 8 phases of 2025')
+  puts
+
+  puts '3. Next 6 phases starting from 2025-08-01:'
+  puts '-' * 45
+  future_phases = MoonPhaseTracker.phases_from_date('2025-08-01', 6)
+  puts tracker.format_phases(future_phases, 'Upcoming phases')
+  puts
+
+  puts '4. Current month phases:'
+  puts '-' * 25
+  current_phases = tracker.current_month_phases
+  if current_phases.any?
+    puts tracker.format_phases(current_phases, 'Current month phases')
+  else
+    puts 'No phases found for the current month.'
+  end
+  puts
+
+  puts '5. Next moon phase:'
+  puts '-' * 25
+  next_phase = tracker.next_phase
+  if next_phase
+    puts next_phase
+    puts "Details: #{next_phase.to_h}"
+  else
+    puts 'Could not retrieve the next phase.'
+  end
+  puts
+
+  puts '6. Different phase representations:'
+  puts '-' * 42
+  if august_phases.any?
+    phase = august_phases.first
+    puts "String: #{phase}"
+    puts "Hash: #{phase.to_h}"
+    puts "Symbol: #{phase.symbol}"
+    puts "Formatted date: #{phase.formatted_date}"
+    puts "Formatted time: #{phase.formatted_time}"
+  end
+rescue MoonPhaseTracker::NetworkError => e
+  puts "Network error: #{e.message}"
+  puts 'Please check your internet connection.'
+rescue MoonPhaseTracker::APIError => e
+  puts "API error: #{e.message}"
+  puts 'The service may be temporarily unavailable.'
+rescue MoonPhaseTracker::InvalidDateError => e
+  puts "Date error: #{e.message}"
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+end
+
+puts
+puts '=== End of Examples ==='

data/lib/moon_phase_tracker/client.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require_relative "rate_limiter"
+
+module MoonPhaseTracker
+  class Client
+    BASE_URL = "https://aa.usno.navy.mil/api/moon/phases"
+    TIMEOUT = 10
+
+    def initialize(rate_limiter: nil)
+      @uri_cache = {}
+      @rate_limiter = rate_limiter || create_default_rate_limiter
+    end
+
+    def phases_from_date(date, num_phases = 12)
+      validate_date_format!(date)
+      validate_num_phases!(num_phases)
+
+      params = { date: date, nump: num_phases }
+      make_request("#{BASE_URL}/date", params)
+    end
+
+    def phases_for_year(year)
+      validate_year!(year)
+
+      params = { year: year }
+      make_request("#{BASE_URL}/year", params)
+    end
+
+    def rate_limit_info
+      @rate_limiter&.configuration
+    end
+
+    private
+
+    def create_default_rate_limiter
+      return nil if ENV["MOON_PHASE_RATE_LIMIT"] == "0" || ENV["MOON_PHASE_RATE_LIMIT"] == "false"
+
+      RateLimiter.new
+    end
+
+    def make_request(endpoint, params = {})
+      uri = build_uri(endpoint, params)
+
+      @rate_limiter&.throttle
+
+      begin
+        response = fetch_with_timeout(uri)
+        parse_response(response)
+      rescue Net::TimeoutError, Net::OpenTimeout, Net::ReadTimeout => e
+        raise NetworkError, "Request timeout: #{e.message}"
+      rescue Net::HTTPError, SocketError => e
+        raise NetworkError, "Network error: #{e.message}"
+      rescue JSON::ParserError => e
+        raise APIError, "Invalid JSON response: #{e.message}"
+      end
+    end
+
+    def build_uri(endpoint, params)
+      cache_key = "#{endpoint}_#{params.hash}"
+
+      @uri_cache[cache_key] ||= begin
+        uri = URI(endpoint)
+        uri.query = URI.encode_www_form(params) unless params.empty?
+        uri
+      end
+    end
+
+    def fetch_with_timeout(uri)
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                          open_timeout: TIMEOUT, read_timeout: TIMEOUT) do |http|
+        request = Net::HTTP::Get.new(uri)
+        request["User-Agent"] = "MoonPhaseTracker/#{MoonPhaseTracker::VERSION}"
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise APIError, "API request failed: #{response.code} - #{response.message}"
+        end
+
+        response
+      end
+    end
+
+    def parse_response(response)
+      data = JSON.parse(response.body)
+
+      raise APIError, "API error: #{data['error']}" if data["error"]
+
+      data
+    end
+
+    def validate_date_format!(date)
+      return if date.match?(/^\d{4}-\d{1,2}-\d{1,2}$/)
+
+      raise InvalidDateError, "Date must be in YYYY-MM-DD format"
+    end
+
+    def validate_num_phases!(num_phases)
+      return if num_phases.is_a?(Integer) && num_phases.between?(1, 99)
+
+      raise InvalidDateError, "Number of phases must be between 1 and 99"
+    end
+
+    def validate_year!(year)
+      current_year = Date.today.year
+
+      return if year.is_a?(Integer) && year.between?(1700, current_year + 10)
+
+      raise InvalidDateError, "Year must be between 1700 and #{current_year + 10}"
+    end
+  end
+end

data/lib/moon_phase_tracker/phase/comparator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module MoonPhaseTracker
+  class Phase
+    class Comparator
+      def self.compare_phases(phase_a, phase_b)
+        return nil unless phases_comparable?(phase_a, phase_b)
+
+        date_comparison = compare_dates(phase_a.date, phase_b.date)
+        return date_comparison unless date_comparison.zero?
+
+        compare_times(phase_a.time, phase_b.time)
+      end
+
+      def self.in_month?(phase_date, year, month)
+        return false unless phase_date
+
+        phase_date.year == year && phase_date.month == month
+      end
+
+      def self.in_year?(phase_date, year)
+        return false unless phase_date
+
+        phase_date.year == year
+      end
+
+      def self.phases_comparable?(phase_a, phase_b)
+        phase_a.is_a?(Phase) && phase_b.is_a?(Phase)
+      end
+
+      def self.compare_dates(date_a, date_b)
+        date_a <=> date_b
+      end
+
+      def self.compare_times(time_a, time_b)
+        time_a <=> time_b
+      end
+
+      private_class_method :phases_comparable?, :compare_dates, :compare_times
+    end
+  end
+end

data/lib/moon_phase_tracker/phase/formatter.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module MoonPhaseTracker
+  class Phase
+    class Formatter
+      INVALID_DATE_MESSAGE = "Invalid date"
+      INVALID_TIME_MESSAGE = "Invalid time"
+      DATE_FORMAT = "%Y-%m-%d"
+      TIME_FORMAT = "%H:%M"
+
+      def self.format_date(date)
+        return INVALID_DATE_MESSAGE unless date
+
+        date.strftime(DATE_FORMAT)
+      end
+
+      def self.format_time(time)
+        return INVALID_TIME_MESSAGE unless time
+
+        time.strftime(TIME_FORMAT)
+      end
+
+      def self.format_phase_description(name, symbol, date, time)
+        formatted_date = format_date(date)
+        formatted_time = format_time(time)
+
+        "#{symbol} #{name} - #{formatted_date} at #{formatted_time}"
+      end
+
+      def self.build_hash_representation(phase_attributes)
+        {
+          name: phase_attributes[:name],
+          phase_type: phase_attributes[:phase_type],
+          date: format_date(phase_attributes[:date]),
+          time: format_time(phase_attributes[:time]),
+          symbol: phase_attributes[:symbol],
+          iso_date: phase_attributes[:date]&.iso8601,
+          utc_time: phase_attributes[:time]&.utc&.iso8601,
+          interpolated: phase_attributes[:interpolated]
+        }
+      end
+    end
+  end
+end

data/lib/moon_phase_tracker/phase/mapper.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module MoonPhaseTracker
+  class Phase
+    class Mapper
+      PHASE_NAMES = {
+        "New Moon" => :new_moon,
+        "First Quarter" => :first_quarter,
+        "Full Moon" => :full_moon,
+        "Last Quarter" => :last_quarter,
+        "Waxing Crescent" => :waxing_crescent,
+        "Waxing Gibbous" => :waxing_gibbous,
+        "Waning Gibbous" => :waning_gibbous,
+        "Waning Crescent" => :waning_crescent
+      }.freeze
+
+      PHASE_SYMBOLS = {
+        new_moon: "🌑",
+        waxing_crescent: "🌒",
+        first_quarter: "🌓",
+        waxing_gibbous: "🌔",
+        full_moon: "🌕",
+        waning_gibbous: "🌖",
+        last_quarter: "🌗",
+        waning_crescent: "🌘"
+      }.freeze
+
+      DEFAULT_PHASE_TYPE = :unknown
+      DEFAULT_SYMBOL = "🌘"
+
+      def self.map_phase_type(phase_name)
+        PHASE_NAMES[phase_name] || DEFAULT_PHASE_TYPE
+      end
+
+      def self.get_phase_symbol(phase_type)
+        PHASE_SYMBOLS[phase_type] || DEFAULT_SYMBOL
+      end
+
+      def self.available_phase_names
+        PHASE_NAMES.keys
+      end
+
+      def self.available_phase_types
+        PHASE_NAMES.values
+      end
+
+      def self.valid_phase_name?(phase_name)
+        PHASE_NAMES.key?(phase_name)
+      end
+
+      def self.valid_phase_type?(phase_type)
+        PHASE_SYMBOLS.key?(phase_type)
+      end
+    end
+  end
+end

data/lib/moon_phase_tracker/phase/parser.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+
+module MoonPhaseTracker
+  class Phase
+    class Parser
+      def self.build_date(phase_data)
+        year = phase_data["year"]
+        month = phase_data["month"]
+        day = phase_data["day"]
+
+        return nil unless valid_date_components?(year, month, day)
+
+        Date.new(year.to_i, month.to_i, day.to_i)
+      rescue Date::Error
+        nil
+      end
+
+      def self.parse_time(time_string)
+        return nil unless time_string
+
+        Time.parse("#{time_string} UTC")
+      rescue ArgumentError
+        nil
+      end
+
+      def self.valid_date_components?(year, month, day)
+        year && month && day
+      end
+
+      private_class_method :valid_date_components?
+    end
+  end
+end

data/lib/moon_phase_tracker/phase.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "phase/parser"
+require_relative "phase/formatter"
+require_relative "phase/comparator"
+require_relative "phase/mapper"
+
+module MoonPhaseTracker
+  class Phase
+    include Comparable
+
+    attr_reader :name, :date, :time, :phase_type, :interpolated
+
+    def initialize(phase_data, interpolated: false)
+      @name = phase_data["phase"]
+      @phase_type = Mapper.map_phase_type(@name)
+      @date = Parser.build_date(phase_data)
+      @time = Parser.parse_time(phase_data["time"])
+      @interpolated = interpolated
+    end
+
+    def formatted_date
+      Formatter.format_date(@date)
+    end
+
+    def formatted_time
+      Formatter.format_time(@time)
+    end
+
+    def symbol
+      Mapper.get_phase_symbol(@phase_type)
+    end
+
+    def to_s
+      Formatter.format_phase_description(@name, symbol, @date, @time)
+    end
+
+    def to_h
+      phase_attributes = {
+        name: @name,
+        phase_type: @phase_type,
+        date: @date,
+        time: @time,
+        symbol: symbol,
+        interpolated: @interpolated
+      }
+
+      Formatter.build_hash_representation(phase_attributes)
+    end
+
+    def <=>(other)
+      Comparator.compare_phases(self, other)
+    end
+
+    def in_month?(year, month)
+      Comparator.in_month?(@date, year, month)
+    end
+
+    def in_year?(year)
+      Comparator.in_year?(@date, year)
+    end
+  end
+end

data/lib/moon_phase_tracker/phase_calculator/cycle_estimator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative "../phase"
+
+module MoonPhaseTracker
+  class PhaseCalculator
+    class CycleEstimator
+      LUNAR_CYCLE_DAYS = 29.530588853
+      PHASE_INTERVAL_DAYS = LUNAR_CYCLE_DAYS / 4.0
+      DEFAULT_TIME = "12:00"
+
+      def estimate_next_cycle_phase(last_phase)
+        return nil unless valid_phase_for_estimation?(last_phase)
+
+        estimated_date = calculate_estimated_date(last_phase)
+        phase_data = build_estimated_phase_data(estimated_date, last_phase)
+
+        Phase.new(phase_data)
+      rescue Date::Error, ArgumentError => e
+        warn "Failed to estimate next cycle phase: #{e.class}"
+        nil
+      end
+
+      private
+
+      def valid_phase_for_estimation?(phase)
+        phase && phase.date
+      end
+
+      def calculate_estimated_date(last_phase)
+        last_phase.date + PHASE_INTERVAL_DAYS
+      end
+
+      def build_estimated_phase_data(estimated_date, reference_phase)
+        {
+          "phase" => "New Moon",
+          "year" => estimated_date.year,
+          "month" => estimated_date.month,
+          "day" => estimated_date.day,
+          "time" => determine_estimated_time(reference_phase)
+        }
+      end
+
+      def determine_estimated_time(reference_phase)
+        return reference_phase.time.strftime("%H:%M") if reference_phase.time
+
+        DEFAULT_TIME
+      end
+    end
+  end
+end