nws 0.2.0

data/lib/nws/alert.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module NWS
+  # Represents a weather alert from the NWS
+  class Alert
+    # @return [String, nil] Alert identifier
+    attr_reader :id
+
+    # @return [String, nil] Description of affected areas
+    attr_reader :area_desc
+
+    # @return [Time, nil] When the alert was sent
+    attr_reader :sent
+
+    # @return [Time, nil] When the alert becomes effective
+    attr_reader :effective
+
+    # @return [Time, nil] When the alert conditions begin
+    attr_reader :onset
+
+    # @return [Time, nil] When the alert expires
+    attr_reader :expires
+
+    # @return [Time, nil] When the alert conditions end
+    attr_reader :ends
+
+    # @return [String, nil] Alert status (e.g., "Actual", "Test")
+    attr_reader :status
+
+    # @return [String, nil] Message type (e.g., "Alert", "Update", "Cancel")
+    attr_reader :message_type
+
+    # @return [String, nil] Severity level (e.g., "Extreme", "Severe", "Moderate", "Minor")
+    attr_reader :severity
+
+    # @return [String, nil] Certainty level (e.g., "Observed", "Likely", "Possible")
+    attr_reader :certainty
+
+    # @return [String, nil] Urgency level (e.g., "Immediate", "Expected", "Future")
+    attr_reader :urgency
+
+    # @return [String, nil] Event type (e.g., "Tornado Warning", "Winter Storm Watch")
+    attr_reader :event
+
+    # @return [String, nil] Name of the sending organization
+    attr_reader :sender_name
+
+    # @return [String, nil] Alert headline
+    attr_reader :headline
+
+    # @return [String, nil] Detailed description of the alert
+    attr_reader :description
+
+    # @return [String, nil] Instructions for the public
+    attr_reader :instruction
+
+    # @return [String, nil] Recommended response type
+    attr_reader :response
+
+    # @return [Array<String>] URLs of affected forecast zones
+    attr_reader :affected_zones
+
+    # @return [Hash] Raw API response data
+    attr_reader :raw_data
+
+    # Initialize an Alert from API response data
+    #
+    # @param data [Hash] Parsed JSON response from the alerts API
+    def initialize(data)
+      @raw_data = data
+      parse_data(data)
+    end
+
+    # Fetch alerts from the NWS API
+    #
+    # @param state [String, nil] Two-letter state code to filter alerts
+    # @param point [Array<Float>, nil] Latitude and longitude pair [lat, lon]
+    # @param zone [String, nil] NWS zone identifier
+    # @param active [Boolean] Whether to fetch only active alerts
+    # @param client [Client] NWS API client instance
+    # @return [Array<Alert>] Array of Alert objects
+    def self.fetch(state: nil, point: nil, zone: nil, active: true, client: NWS.client)
+      params = {}
+      params[:status] = "actual" if active
+
+      path = if state
+               params[:area] = state.upcase
+               "/alerts/active"
+             elsif point
+               params[:point] = "#{point[0]},#{point[1]}"
+               "/alerts/active"
+             elsif zone
+               "/alerts/active/zone/#{zone}"
+             else
+               "/alerts/active"
+             end
+
+      data = client.get(path, params: params)
+      features = data["features"] || []
+      features.map { |f| new(f) }
+    end
+
+    # Fetch all available alert types
+    #
+    # @param client [Client] NWS API client instance
+    # @return [Array<String>] Array of alert event type names
+    def self.types(client: NWS.client)
+      data = client.get("/alerts/types")
+      data["eventTypes"] || []
+    end
+
+    # Check if the alert is currently active
+    #
+    # @return [Boolean] True if the alert has not yet expired
+    def active?
+      return false unless @expires
+      Time.now < @expires
+    end
+
+    # Check if this is a severe alert
+    #
+    # @return [Boolean] True if severity is "Extreme" or "Severe"
+    def severe?
+      %w[Extreme Severe].include?(@severity)
+    end
+
+    # Check if this is a warning
+    #
+    # @return [Boolean] True if the event name contains "warning"
+    def warning?
+      !!@event&.downcase&.include?("warning")
+    end
+
+    # Check if this is a watch
+    #
+    # @return [Boolean] True if the event name contains "watch"
+    def watch?
+      !!@event&.downcase&.include?("watch")
+    end
+
+    # Check if this is an advisory
+    #
+    # @return [Boolean] True if the event name contains "advisory"
+    def advisory?
+      !!@event&.downcase&.include?("advisory")
+    end
+
+    # Get a formatted string representation of the alert
+    #
+    # @return [String] Multi-line formatted alert summary
+    def to_s
+      lines = []
+      lines << "#{@event}"
+      lines << "  Severity: #{@severity} | Urgency: #{@urgency} | Certainty: #{@certainty}"
+      lines << "  Areas: #{@area_desc}"
+      lines << "  Effective: #{@effective&.strftime('%Y-%m-%d %I:%M %p')}"
+      lines << "  Expires: #{@expires&.strftime('%Y-%m-%d %I:%M %p')}"
+      lines << ""
+      lines << "  #{@headline}"
+      lines.join("\n")
+    end
+
+    # Get a detailed formatted string representation of the alert
+    #
+    # @return [String] Multi-line detailed alert with description and instructions
+    def detailed
+      lines = []
+      lines << "#{@event}"
+      lines << "=" * @event.length
+      lines << ""
+      lines << "Severity: #{@severity}"
+      lines << "Urgency: #{@urgency}"
+      lines << "Certainty: #{@certainty}"
+      lines << ""
+      lines << "Areas Affected:"
+      lines << "  #{@area_desc}"
+      lines << ""
+      lines << "Timing:"
+      lines << "  Effective: #{@effective&.strftime('%Y-%m-%d %I:%M %p')}"
+      lines << "  Expires: #{@expires&.strftime('%Y-%m-%d %I:%M %p')}"
+      lines << ""
+      lines << "Headline:"
+      lines << "  #{@headline}"
+      lines << ""
+      lines << "Description:"
+      wrap_text(@description, 80).each { |line| lines << "  #{line}" }
+      if @instruction
+        lines << ""
+        lines << "Instructions:"
+        wrap_text(@instruction, 80).each { |line| lines << "  #{line}" }
+      end
+      lines.join("\n")
+    end
+
+    private
+
+    # Parse API response data into instance variables
+    #
+    # @param data [Hash] Parsed JSON response
+    # @return [void]
+    def parse_data(data)
+      props = data["properties"] || {}
+
+      @id = props["id"]
+      @area_desc = props["areaDesc"]
+      @sent = parse_time(props["sent"])
+      @effective = parse_time(props["effective"])
+      @onset = parse_time(props["onset"])
+      @expires = parse_time(props["expires"])
+      @ends = parse_time(props["ends"])
+      @status = props["status"]
+      @message_type = props["messageType"]
+      @severity = props["severity"]
+      @certainty = props["certainty"]
+      @urgency = props["urgency"]
+      @event = props["event"]
+      @sender_name = props["senderName"]
+      @headline = props["headline"]
+      @description = props["description"]
+      @instruction = props["instruction"]
+      @response = props["response"]
+      @affected_zones = props["affectedZones"] || []
+    end
+
+    # Parse an ISO8601 time string
+    #
+    # @param str [String, nil] Time string
+    # @return [Time, nil] Parsed time or nil
+    def parse_time(str)
+      return nil unless str
+      Time.parse(str)
+    rescue ArgumentError
+      nil
+    end
+
+    # Wrap text to a specified width
+    #
+    # @param text [String, nil] Text to wrap
+    # @param width [Integer] Maximum line width
+    # @return [Array<String>] Array of wrapped lines
+    def wrap_text(text, width)
+      return [] unless text
+      text.split("\n").flat_map do |paragraph|
+        if paragraph.strip.empty?
+          [""]
+        else
+          words = paragraph.split
+          lines = []
+          current_line = ""
+
+          words.each do |word|
+            if current_line.empty?
+              current_line = word
+            elsif (current_line.length + word.length + 1) <= width
+              current_line += " #{word}"
+            else
+              lines << current_line
+              current_line = word
+            end
+          end
+          lines << current_line unless current_line.empty?
+          lines
+        end
+      end
+    end
+  end
+end

data/lib/nws/client.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module NWS
+  # HTTP client for making requests to the NWS API
+  class Client
+    # Base URL for the NWS API
+    BASE_URL = "https://api.weather.gov"
+
+    # @return [String] User-Agent string sent with requests
+    attr_reader :user_agent
+
+    # Initialize a new NWS API client
+    #
+    # @param user_agent [String, nil] Custom User-Agent string. If nil, uses default.
+    def initialize(user_agent: nil)
+      @user_agent = user_agent || default_user_agent
+    end
+
+    # Make a GET request to the NWS API
+    #
+    # @param path [String] API path (e.g., "/points/38.8977,-77.0365")
+    # @param params [Hash] Query parameters
+    # @return [Hash] Parsed JSON response
+    # @raise [NotFoundError] if resource is not found (404)
+    # @raise [RateLimitError] if rate limit exceeded (429)
+    # @raise [ServerError] if server error (5xx)
+    # @raise [APIError] for other API errors
+    def get(path, params: {})
+      uri = build_uri(path, params)
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = user_agent
+      request["Accept"] = "application/geo+json"
+
+      response = execute_request(uri, request)
+      handle_response(response)
+    end
+
+    # Make a GET request to a full URL
+    #
+    # @param url [String] Full URL to request
+    # @return [Hash] Parsed JSON response
+    # @raise [NotFoundError] if resource is not found (404)
+    # @raise [RateLimitError] if rate limit exceeded (429)
+    # @raise [ServerError] if server error (5xx)
+    # @raise [APIError] for other API errors
+    def get_url(url)
+      uri = URI.parse(url)
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = user_agent
+      request["Accept"] = "application/geo+json"
+
+      response = execute_request(uri, request)
+      handle_response(response)
+    end
+
+    private
+
+    # Build a URI from path and params
+    #
+    # @param path [String] API path
+    # @param params [Hash] Query parameters
+    # @return [URI] Constructed URI
+    def build_uri(path, params)
+      uri = URI.parse("#{BASE_URL}#{path}")
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      uri
+    end
+
+    # Execute an HTTP request
+    #
+    # @param uri [URI] Request URI
+    # @param request [Net::HTTP::Request] Request object
+    # @return [Net::HTTPResponse] Response object
+    def execute_request(uri, request)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = 10
+      http.read_timeout = 30
+      http.request(request)
+    end
+
+    # Handle API response, raising errors for non-success codes
+    #
+    # @param response [Net::HTTPResponse] Response object
+    # @return [Hash] Parsed JSON response
+    # @raise [NotFoundError, RateLimitError, ServerError, APIError] for error responses
+    def handle_response(response)
+      case response.code.to_i
+      when 200..299
+        JSON.parse(response.body)
+      when 404
+        raise NotFoundError.new("Resource not found", status_code: 404, response_body: response.body)
+      when 429
+        raise RateLimitError.new("Rate limit exceeded. Retry after a few seconds.", status_code: 429, response_body: response.body)
+      when 500..599
+        raise ServerError.new("Server error: #{response.code}", status_code: response.code.to_i, response_body: response.body)
+      else
+        raise APIError.new("API error: #{response.code}", status_code: response.code.to_i, response_body: response.body)
+      end
+    end
+
+    # Generate default User-Agent string
+    #
+    # @return [String] Default User-Agent
+    def default_user_agent
+      "(nws-ruby-gem, #{NWS::VERSION})"
+    end
+  end
+end

data/lib/nws/errors.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module NWS
+  # Base error class for all NWS errors
+  class Error < StandardError; end
+
+  # Error raised when the NWS API returns an error response
+  class APIError < Error
+    # @return [Integer, nil] HTTP status code from the API response
+    attr_reader :status_code
+
+    # @return [String, nil] Raw response body from the API
+    attr_reader :response_body
+
+    # @param message [String] Error message
+    # @param status_code [Integer, nil] HTTP status code
+    # @param response_body [String, nil] Raw response body
+    def initialize(message, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  # Error raised when a requested resource is not found (404)
+  class NotFoundError < APIError; end
+
+  # Error raised when rate limit is exceeded (429)
+  class RateLimitError < APIError; end
+
+  # Error raised when the server returns a 5xx error
+  class ServerError < APIError; end
+
+  # Error raised when invalid coordinates are provided
+  class InvalidCoordinatesError < Error; end
+end

data/lib/nws/forecast.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+module NWS
+  # Represents a 7-day weather forecast with 12-hour periods
+  class Forecast
+    # @return [Point, nil] The point this forecast is for
+    attr_reader :point
+
+    # @return [Time, nil] When the forecast was last updated
+    attr_reader :updated_at
+
+    # @return [Array<ForecastPeriod>] Forecast periods (typically 14, covering 7 days)
+    attr_reader :periods
+
+    # @return [Hash] Raw API response data
+    attr_reader :raw_data
+
+    # Initialize a Forecast from API response data
+    #
+    # @param data [Hash] Parsed JSON response from the forecast API
+    # @param point [Point, nil] The point this forecast is for
+    def initialize(data, point: nil)
+      @point = point
+      @raw_data = data
+      parse_data(data)
+    end
+
+    # Get today's forecast period
+    #
+    # @return [ForecastPeriod] First forecast period (typically today)
+    def today
+      @periods.first
+    end
+
+    # Get tonight's forecast period
+    #
+    # @return [ForecastPeriod, nil] Tonight's forecast period or nil if not found
+    def tonight
+      @periods.find { |p| p.name.downcase.include?("tonight") || p.name.downcase.include?("night") }
+    end
+
+    # Get a formatted string representation of the forecast
+    #
+    # @return [String] Multi-line formatted forecast
+    def to_s
+      lines = []
+      lines << "Forecast for #{point&.location_string || 'Unknown Location'}"
+      lines << "Updated: #{updated_at&.strftime('%Y-%m-%d %I:%M %p')}"
+      lines << ""
+
+      @periods.each do |period|
+        lines << "#{period.name}: #{period.temperature}°#{period.temperature_unit}"
+        lines << "  #{period.short_forecast}"
+        lines << ""
+      end
+
+      lines.join("\n")
+    end
+
+    # Get a detailed formatted string representation of the forecast
+    #
+    # @return [String] Multi-line detailed forecast
+    def detailed
+      lines = []
+      lines << "Forecast for #{point&.location_string || 'Unknown Location'}"
+      lines << "Updated: #{updated_at&.strftime('%Y-%m-%d %I:%M %p')}"
+      lines << ""
+
+      @periods.each do |period|
+        lines << "#{period.name}:"
+        lines << "  #{period.detailed_forecast}"
+        lines << ""
+      end
+
+      lines.join("\n")
+    end
+
+    private
+
+    # Parse API response data into instance variables
+    #
+    # @param data [Hash] Parsed JSON response
+    # @return [void]
+    def parse_data(data)
+      props = data["properties"] || {}
+      @updated_at = parse_time(props["updateTime"])
+
+      raw_periods = props["periods"] || []
+      @periods = raw_periods.map { |p| ForecastPeriod.new(p) }
+    end
+
+    # Parse an ISO8601 time string
+    #
+    # @param str [String, nil] Time string
+    # @return [Time, nil] Parsed time or nil
+    def parse_time(str)
+      return nil unless str
+      Time.parse(str)
+    rescue ArgumentError
+      nil
+    end
+  end
+
+  # Represents a single forecast period (typically 12 hours)
+  class ForecastPeriod
+    # @return [Integer] Period number
+    attr_reader :number
+
+    # @return [String] Period name (e.g., "Today", "Tonight", "Friday")
+    attr_reader :name
+
+    # @return [Time, nil] Start time of the period
+    attr_reader :start_time
+
+    # @return [Time, nil] End time of the period
+    attr_reader :end_time
+
+    # @return [Boolean] Whether this is a daytime period
+    attr_reader :is_daytime
+
+    # @return [Integer] Temperature value
+    attr_reader :temperature
+
+    # @return [String] Temperature unit (e.g., "F")
+    attr_reader :temperature_unit
+
+    # @return [String, nil] Temperature trend
+    attr_reader :temperature_trend
+
+    # @return [Integer, nil] Probability of precipitation (0-100)
+    attr_reader :probability_of_precipitation
+
+    # @return [String] Wind speed (e.g., "10 mph")
+    attr_reader :wind_speed
+
+    # @return [String] Wind direction (e.g., "NW")
+    attr_reader :wind_direction
+
+    # @return [String] Short forecast description
+    attr_reader :short_forecast
+
+    # @return [String] Detailed forecast description
+    attr_reader :detailed_forecast
+
+    # @return [String] URL to forecast icon
+    attr_reader :icon
+
+    # @return [Hash] Raw API response data
+    attr_reader :raw_data
+
+    # Initialize a ForecastPeriod from API response data
+    #
+    # @param data [Hash] Parsed JSON period data
+    def initialize(data)
+      @raw_data = data
+      parse_data(data)
+    end
+
+    # Check if this is a daytime period
+    #
+    # @return [Boolean] True if daytime period
+    def daytime?
+      @is_daytime
+    end
+
+    # Get a formatted string representation of the period
+    #
+    # @return [String] Formatted period string
+    def to_s
+      "#{@name}: #{@temperature}°#{@temperature_unit} - #{@short_forecast}"
+    end
+
+    private
+
+    # Parse API response data into instance variables
+    #
+    # @param data [Hash] Parsed JSON period data
+    # @return [void]
+    def parse_data(data)
+      @number = data["number"]
+      @name = data["name"]
+      @start_time = parse_time(data["startTime"])
+      @end_time = parse_time(data["endTime"])
+      @is_daytime = data["isDaytime"]
+      @temperature = data["temperature"]
+      @temperature_unit = data["temperatureUnit"]
+      @temperature_trend = data["temperatureTrend"]
+      @probability_of_precipitation = data.dig("probabilityOfPrecipitation", "value")
+      @wind_speed = data["windSpeed"]
+      @wind_direction = data["windDirection"]
+      @short_forecast = data["shortForecast"]
+      @detailed_forecast = data["detailedForecast"]
+      @icon = data["icon"]
+    end
+
+    # Parse an ISO8601 time string
+    #
+    # @param str [String, nil] Time string
+    # @return [Time, nil] Parsed time or nil
+    def parse_time(str)
+      return nil unless str
+      Time.parse(str)
+    rescue ArgumentError
+      nil
+    end
+  end
+end