nws 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e20ffd779d08818af88ceebe121319e131fc1510b2c8a613dc2a6aa289fd94bb
+  data.tar.gz: ebe575f2294c397f3cc9e614bf42786635766cb03f80abe3479d6adbffcb4859
+SHA512:
+  metadata.gz: 5ab2b2ab1fab199ea512c5dc85ebfb9d4e24232b2ff75163f505f59a25536a7764550f5c92fabd936e5a9b7469cfa77e02ac9fe286717269f641a2ab31eca00c
+  data.tar.gz: cc8d57ccfb357711376b5945244e641d3faeee4495e549ac7e0d8de24f34b2899a8f24b01f01c617c042ab2c70d837e0adb45a081d1811f77faccf519debedbb

data/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>

data/README.md

@@ -0,0 +1,55 @@
+# NWS
+
+Ruby client for the National Weather Service API.
+
+## Installation
+
+```
+gem install nws
+```
+
+## CLI Usage
+
+```bash
+nws forecast --location "Denver, CO"
+nws hourly --lat 39.7456 --lon -104.9892
+nws current --location "80202"
+nws alerts --state CO
+```
+
+Use `-o json` for JSON output.
+
+## Library Usage
+
+```ruby
+require 'nws'
+
+# 7-day forecast
+forecast = NWS.forecast(39.7456, -104.9892)
+puts forecast.today
+
+# Hourly forecast
+hourly = NWS.hourly_forecast(39.7456, -104.9892)
+hourly.next_hours(12).each { |h| puts h }
+
+# Current conditions
+conditions = NWS.current_conditions(39.7456, -104.9892)
+puts conditions.summary
+
+# Alerts
+alerts = NWS.alerts(state: "CO")
+alerts.each { |a| puts a.headline }
+```
+
+## Geocoding
+
+Location lookups use OpenStreetMap Nominatim with rate limiting and caching.
+
+## License
+
+Public domain. See LICENSE.
+
+## Note
+
+This code and repository are unofficial and unaffiliated with the National 
+Weathers Service, NOAA, and any other government or official bodies.

data/bin/nws

@@ -0,0 +1,429 @@
+#!/usr/bin/env ruby
+
+require "optparse"
+require_relative "../lib/nws"
+
+module NWS
+  class CLI
+    def initialize(args)
+      @args = args
+      @options = {}
+    end
+
+    def run
+      command = @args.shift
+
+      case command
+      when "forecast", "f"
+        forecast_command
+      when "hourly", "h"
+        hourly_command
+      when "current", "c", "conditions"
+        current_command
+      when "alerts", "a"
+        alerts_command
+      when "point", "p"
+        point_command
+      when "stations", "s"
+        stations_command
+      when "help", nil, "-h", "--help"
+        help_command
+      when "version", "-v", "--version"
+        version_command
+      else
+        puts "Unknown command: #{command}"
+        puts "Run 'nws help' for usage information."
+        exit 1
+      end
+    rescue NWS::InvalidCoordinatesError => e
+      puts "Error: #{e.message}"
+      exit 1
+    rescue NWS::NotFoundError => e
+      puts "Error: Location not found. Please check your coordinates."
+      exit 1
+    rescue NWS::RateLimitError => e
+      puts "Error: Rate limit exceeded. Please wait a few seconds and try again."
+      exit 1
+    rescue NWS::APIError => e
+      puts "API Error: #{e.message}"
+      exit 1
+    rescue StandardError => e
+      puts "Error: #{e.message}"
+      exit 1
+    end
+
+    private
+
+    def parse_location_options(parser)
+      parser.on("--lat LAT", Float, "Latitude") { |v| @options[:lat] = v }
+      parser.on("--lon LON", Float, "Longitude") { |v| @options[:lon] = v }
+      parser.on("--location LOCATION", "Coordinates (LAT,LON) or place name") do |v|
+        @options[:location_input] = v
+      end
+    end
+
+    def parse_output_format_option(parser)
+      parser.on("-o", "--output-format FORMAT", %w[text json], "Output format: text (default), json") do |v|
+        @options[:output_format] = v
+      end
+    end
+
+    def json_output?
+      @options[:output_format] == "json"
+    end
+
+    def output(text_output, json_data)
+      if json_output?
+        puts JSON.pretty_generate(json_data)
+      else
+        puts text_output
+        print_attribution
+      end
+    end
+
+    def require_location!
+      resolve_location! if @options[:location_input]
+
+      unless @options[:lat] && @options[:lon]
+        puts "Error: Location required. Use --lat and --lon or --location"
+        exit 1
+      end
+    end
+
+    def resolve_location!
+      input = @options[:location_input]
+      return unless input
+
+      if coordinate_format?(input)
+        lat, lon = input.split(",").map(&:strip).map(&:to_f)
+        @options[:lat] = lat
+        @options[:lon] = lon
+      else
+        geocoder = NWS::Geocoder.new
+        result = geocoder.geocode(input)
+        @options[:lat] = result.latitude
+        @options[:lon] = result.longitude
+        @options[:resolved_location] = result.display_name
+        @options[:geocoded] = true
+        @options[:from_cache] = result.from_cache?
+      end
+    end
+
+    def print_attribution
+      return unless @options[:geocoded]
+      puts ""
+      puts NWS::Geocoder.attribution
+    end
+
+    def coordinate_format?(input)
+      # Check if input looks like "lat,lon" (two numbers separated by comma)
+      parts = input.split(",")
+      return false unless parts.length == 2
+
+      parts.all? do |part|
+        part.strip.match?(/\A-?\d+(\.\d+)?\z/)
+      end
+    end
+
+    def forecast_command
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: nws forecast [options]"
+        parse_location_options(opts)
+        parse_output_format_option(opts)
+        opts.on("--detailed", "-d", "Show detailed forecast") { @options[:detailed] = true }
+      end
+      parser.parse!(@args)
+      require_location!
+
+      forecast = NWS.forecast(@options[:lat], @options[:lon])
+
+      text_output = @options[:detailed] ? forecast.detailed : forecast.to_s
+      json_data = {
+        location: forecast.point&.location_string,
+        updated_at: forecast.updated_at&.iso8601,
+        periods: forecast.periods.map do |p|
+          {
+            name: p.name,
+            start_time: p.start_time&.iso8601,
+            end_time: p.end_time&.iso8601,
+            is_daytime: p.daytime?,
+            temperature: p.temperature,
+            temperature_unit: p.temperature_unit,
+            wind_speed: p.wind_speed,
+            wind_direction: p.wind_direction,
+            short_forecast: p.short_forecast,
+            detailed_forecast: p.detailed_forecast,
+            probability_of_precipitation: p.probability_of_precipitation
+          }
+        end
+      }
+
+      output(text_output, json_data)
+    end
+
+    def hourly_command
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: nws hourly [options]"
+        parse_location_options(opts)
+        parse_output_format_option(opts)
+        opts.on("--hours N", Integer, "Number of hours to show (default: 24)") { |v| @options[:hours] = v }
+      end
+      parser.parse!(@args)
+      require_location!
+
+      forecast = NWS.hourly_forecast(@options[:lat], @options[:lon])
+      hours = @options[:hours] || 24
+
+      text_output = forecast.to_s(hours: hours)
+      json_data = {
+        location: forecast.point&.location_string,
+        updated_at: forecast.updated_at&.iso8601,
+        periods: forecast.next_hours(hours).map do |p|
+          {
+            start_time: p.start_time&.iso8601,
+            end_time: p.end_time&.iso8601,
+            is_daytime: p.daytime?,
+            temperature: p.temperature,
+            temperature_unit: p.temperature_unit,
+            wind_speed: p.wind_speed,
+            wind_direction: p.wind_direction,
+            short_forecast: p.short_forecast,
+            probability_of_precipitation: p.probability_of_precipitation
+          }
+        end
+      }
+
+      output(text_output, json_data)
+    end
+
+    def current_command
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: nws current [options]"
+        parse_location_options(opts)
+        parse_output_format_option(opts)
+      end
+      parser.parse!(@args)
+      require_location!
+
+      observation = NWS.current_conditions(@options[:lat], @options[:lon])
+
+      text_output = observation.to_s
+      json_data = {
+        timestamp: observation.timestamp&.iso8601,
+        text_description: observation.text_description,
+        temperature: {
+          celsius: observation.temperature_c,
+          fahrenheit: observation.temperature_f&.round(1)
+        },
+        dewpoint: {
+          celsius: observation.dewpoint_c,
+          fahrenheit: observation.dewpoint_f&.round(1)
+        },
+        relative_humidity: observation.relative_humidity&.round(1),
+        wind: {
+          speed_mph: observation.wind_speed_mph&.round(1),
+          speed_kmh: observation.wind_speed_kmh,
+          direction: observation.wind_direction,
+          gust_mph: observation.wind_gust_mph&.round(1)
+        },
+        visibility: {
+          meters: observation.visibility_m,
+          miles: observation.visibility_miles
+        },
+        barometric_pressure: {
+          pascals: observation.barometric_pressure,
+          inhg: observation.barometric_pressure_inhg
+        },
+        heat_index: {
+          celsius: observation.heat_index_c,
+          fahrenheit: observation.heat_index_f&.round(1)
+        },
+        wind_chill: {
+          celsius: observation.wind_chill_c,
+          fahrenheit: observation.wind_chill_f&.round(1)
+        }
+      }
+
+      output(text_output, json_data)
+    end
+
+    def alerts_command
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: nws alerts [options]"
+        parse_location_options(opts)
+        parse_output_format_option(opts)
+        opts.on("--state STATE", "Two-letter state code (e.g., CA, TX)") { |v| @options[:state] = v }
+        opts.on("--detailed", "-d", "Show detailed alerts") { @options[:detailed] = true }
+      end
+      parser.parse!(@args)
+
+      resolve_location! if @options[:location_input]
+
+      alerts = if @options[:state]
+                 NWS.alerts(state: @options[:state])
+               elsif @options[:lat] && @options[:lon]
+                 NWS.alerts(point: [@options[:lat], @options[:lon]])
+               else
+                 puts "Error: Provide --state or --lat/--lon"
+                 exit 1
+               end
+
+      if json_output?
+        json_data = {
+          count: alerts.count,
+          alerts: alerts.map do |alert|
+            {
+              id: alert.id,
+              event: alert.event,
+              severity: alert.severity,
+              certainty: alert.certainty,
+              urgency: alert.urgency,
+              area_desc: alert.area_desc,
+              headline: alert.headline,
+              description: alert.description,
+              instruction: alert.instruction,
+              effective: alert.effective&.iso8601,
+              expires: alert.expires&.iso8601,
+              onset: alert.onset&.iso8601,
+              sender_name: alert.sender_name
+            }
+          end
+        }
+        puts JSON.pretty_generate(json_data)
+      else
+        if alerts.empty?
+          puts "No active alerts."
+        else
+          puts "#{alerts.count} active alert(s):\n\n"
+          alerts.each do |alert|
+            if @options[:detailed]
+              puts alert.detailed
+            else
+              puts alert.to_s
+            end
+            puts "\n" + "-" * 60 + "\n\n"
+          end
+        end
+        print_attribution
+      end
+    end
+
+    def point_command
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: nws point [options]"
+        parse_location_options(opts)
+        parse_output_format_option(opts)
+      end
+      parser.parse!(@args)
+      require_location!
+
+      point = NWS.point(@options[:lat], @options[:lon])
+
+      text_output = <<~TEXT
+        Point Information
+          Location: #{point.location_string}
+          Grid: #{point.grid_id} (#{point.grid_x}, #{point.grid_y})
+          Time Zone: #{point.time_zone}
+          Forecast URL: #{point.forecast_url}
+          Hourly Forecast URL: #{point.forecast_hourly_url}
+          Observation Stations URL: #{point.observation_stations_url}
+      TEXT
+
+      json_data = {
+        location: point.location_string,
+        city: point.city,
+        state: point.state,
+        latitude: point.latitude,
+        longitude: point.longitude,
+        grid_id: point.grid_id,
+        grid_x: point.grid_x,
+        grid_y: point.grid_y,
+        time_zone: point.time_zone,
+        forecast_url: point.forecast_url,
+        forecast_hourly_url: point.forecast_hourly_url,
+        observation_stations_url: point.observation_stations_url
+      }
+
+      output(text_output.strip, json_data)
+    end
+
+    def stations_command
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: nws stations [options]"
+        parse_location_options(opts)
+        parse_output_format_option(opts)
+        opts.on("--limit N", Integer, "Number of stations to show") { |v| @options[:limit] = v }
+      end
+      parser.parse!(@args)
+      require_location!
+
+      point = NWS.point(@options[:lat], @options[:lon])
+      stations = point.observation_stations
+      limit = @options[:limit] || 5
+      limited_stations = stations.first(limit)
+
+      text_lines = ["Observation Stations near #{point.location_string}:\n"]
+      limited_stations.each_with_index do |station, i|
+        text_lines << "#{i + 1}. #{station.name} (#{station.station_id})"
+        text_lines << "   Location: #{station.latitude}, #{station.longitude}"
+        text_lines << ""
+      end
+
+      json_data = {
+        location: point.location_string,
+        stations: limited_stations.map do |station|
+          {
+            station_id: station.station_id,
+            name: station.name,
+            latitude: station.latitude,
+            longitude: station.longitude,
+            elevation: station.elevation,
+            time_zone: station.time_zone
+          }
+        end
+      }
+
+      output(text_lines.join("\n"), json_data)
+    end
+
+    def help_command
+      puts <<~HELP
+        NWS - National Weather Service API Client
+
+        Usage: nws <command> [options]
+
+        Commands:
+          forecast, f    Get 7-day forecast
+          hourly, h      Get hourly forecast
+          current, c     Get current conditions
+          alerts, a      Get active weather alerts
+          point, p       Get point/grid information
+          stations, s    List observation stations
+
+        Location Options (required for most commands):
+          --lat LAT            Latitude
+          --lon LON            Longitude
+          --location LOCATION  Coordinates (LAT,LON) or place name
+
+        Output Options:
+          -o, --output-format FORMAT  Output format: text (default), json
+
+        Examples:
+          nws forecast --location "Washington, DC"
+          nws forecast --lat 38.8977 --lon -77.0365
+          nws hourly --location 40.7128,-74.0060 --hours 12
+          nws current --location "New York, NY" -o json
+          nws alerts --state CA
+          nws alerts --location "Los Angeles, CA" --output-format json
+
+        Run 'nws <command> --help' for command-specific options.
+      HELP
+    end
+
+    def version_command
+      puts "nws #{NWS::VERSION}"
+    end
+  end
+end
+
+NWS::CLI.new(ARGV).run