weatherxu 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 85e16dc76187027dc9e39d22a18519601e33ffb95257731b2ed04dec28152e69
+  data.tar.gz: 7642f4a499ec155a472a4e5f0c42e647df90d865fbcec8105210651a1a9770e2
+SHA512:
+  metadata.gz: c56f7ea3667523047b913444750d319b5af09fd5154755114f8d9da0cca59df286015c595de6a26dbfb069cf0092e9fd7e154a19fd0367f799e7087844e1a717
+  data.tar.gz: 778187ae76c3ffffb49f0e53af43ee1d86468a87a14037c041944205862e14f9cd44f49534e58c5224445ed2240fae3db43d43c33a82e472e97cbe36f43136c8

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 WeatherXu
+
+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,152 @@
+# WeatherXu Ruby SDK
+
+Official Ruby SDK for accessing WeatherXu's weather data API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'weatherxu'
+```
+
+And then execute:
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+```bash
+$ gem install weatherxu
+```
+
+## Quick Start
+
+```ruby
+require 'weatherxu'
+
+# Initialize the client
+client = WeatherXu.new(
+  api_key: 'YOUR_API_KEY',
+  units: 'metric'
+)
+
+begin
+  # Get current weather and forecast for New York City
+  weather = client.get_weather(
+    lat: 40.7128,
+    lon: -74.0060,
+    parts: ['currently', 'hourly', 'daily']
+  )
+
+  # Access current conditions
+  puts "Current temperature: #{weather.currently.temperature}°C"
+
+  # Access hourly forecast
+  weather.hourly&.each do |hour|
+    puts "Time: #{hour.forecast_start.strftime('%Y-%m-%d %H:%M')}, " \
+         "Temperature: #{hour.temperature}°C"
+  end
+
+  # Get historical weather data
+  end_time = Time.now.to_i
+  start_time = end_time - (24 * 60 * 60) # 24 hours ago
+
+  historical = client.get_historical(
+    lat: 40.7128,
+    lon: -74.0060,
+    start: start_time,
+    end_time: end_time
+  )
+
+  # Access historical data
+  historical.hourly.each do |record|
+    puts "Time: #{record.forecast_start.strftime('%Y-%m-%d %H:%M')}, " \
+         "Temperature: #{record.temperature}°C"
+  end
+rescue WeatherXu::Error => e
+  puts "Error: #{e.message}"
+  puts "Status code: #{e.status_code}" if e.status_code
+  puts "Error code: #{e.error_code}" if e.error_code
+end
+```
+
+## Features
+
+- Modern Ruby features and best practices
+- Automatic parsing of timestamps to Time objects
+- Comprehensive error handling
+- Support for both metric and imperial units
+- Configurable request timeout
+- Automatic retries with exponential backoff
+
+## API Reference
+
+### Initialization
+
+```ruby
+WeatherXu.new(
+  api_key: String,
+  units: String = "metric",
+  timeout: Integer = 10
+)
+```
+
+### Methods
+
+#### get_weather
+
+Get current weather and forecast data for a location.
+
+```ruby
+get_weather(
+  lat: Float,
+  lon: Float,
+  parts: Array<String> = nil,
+  units: String = nil
+) -> WeatherData
+```
+
+Parameters:
+- `lat`: Latitude (-90 to 90)
+- `lon`: Longitude (-180 to 180)
+- `parts`: Optional array of data blocks to include ('alerts', 'currently', 'hourly', 'daily')
+- `units`: Optional unit system ('metric' or 'imperial')
+
+#### get_historical
+
+Get historical weather data for a location.
+
+```ruby
+get_historical(
+  lat: Float,
+  lon: Float,
+  start: Integer,
+  end_time: Integer,
+  units: String = nil
+) -> HistoricalData
+```
+
+Parameters:
+- `lat`: Latitude (-90 to 90)
+- `lon`: Longitude (-180 to 180)
+- `start`: Start time (Unix timestamp)
+- `end_time`: End time (Unix timestamp)
+- `units`: Optional unit system ('metric' or 'imperial')
+
+## Error Handling
+
+The SDK raises `WeatherXu::Error` for any API or network-related errors. Each error includes:
+- Error message
+- HTTP status code (when available)
+- API error code (when provided by the API)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Requirements
+
+- Ruby 2.7 or higher

data/lib/weatherxu/client.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module WeatherXu
+  # Main client for interacting with the WeatherXu API
+  class Client
+    WEATHER_BASE_URL = "https://api.weatherxu.com/v1"
+    HISTORICAL_BASE_URL = "https://historical.weatherxu.com/v1"
+
+    # @return [String] API key for authentication
+    attr_reader :api_key
+
+    # @return [String] Unit system ('metric' or 'imperial')
+    attr_reader :units
+
+    # @return [Integer] Request timeout in seconds
+    attr_reader :timeout
+
+    # Initialize a new WeatherXu client
+    #
+    # @param api_key [String] Your WeatherXu API key
+    # @param units [String] Unit system ('metric' or 'imperial')
+    # @param timeout [Integer] Request timeout in seconds
+    # @raise [Error] if API key is missing
+    def initialize(api_key:, units: "metric", timeout: 10)
+      raise Error, "API key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @units = units
+      @timeout = timeout
+    end
+
+    # Get current weather and forecast data for a location
+    #
+    # @param lat [Float] Latitude (-90 to 90)
+    # @param lon [Float] Longitude (-180 to 180)
+    # @param parts [Array<String>] Data blocks to include ('alerts', 'currently', 'hourly', 'daily')
+    # @param units [String, nil] Unit system ('metric' or 'imperial')
+    # @return [WeatherData] Weather data response
+    # @raise [Error] if the API request fails
+    def get_weather(lat:, lon:, parts: nil, units: nil)
+      params = {
+        lat: lat,
+        lon: lon,
+        units: units || @units
+      }
+      params[:parts] = parts.join(",") if parts
+
+      response = make_request(
+        :get,
+        "#{WEATHER_BASE_URL}/weather",
+        params
+      )
+
+      WeatherData.new(response)
+    end
+
+    # Get historical weather data for a location
+    #
+    # @param lat [Float] Latitude (-90 to 90)
+    # @param lon [Float] Longitude (-180 to 180)
+    # @param start [Integer] Start time (Unix timestamp)
+    # @param end_time [Integer] End time (Unix timestamp)
+    # @param units [String, nil] Unit system ('metric' or 'imperial')
+    # @return [HistoricalData] Historical weather data response
+    # @raise [Error] if the API request fails
+    def get_historical(lat:, lon:, start:, end_time:, units: nil)
+      params = {
+        lat: lat,
+        lon: lon,
+        start: start,
+        end: end_time,
+        units: units || @units
+      }
+
+      response = make_request(
+        :get,
+        "#{HISTORICAL_BASE_URL}/history",
+        params
+      )
+
+      HistoricalData.new(response)
+    end
+
+    private
+
+    def make_request(method, url, params = {})
+      uri = URI(url)
+      uri.query = URI.encode_www_form(params)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.read_timeout = timeout
+      http.open_timeout = timeout
+
+      request = Net::HTTP::Get.new(uri)
+      request["X-API-KEY"] = api_key
+      request["Content-Type"] = "application/json"
+
+      response = http.request(request)
+      handle_response(response)
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise Error, "Request timed out: #{e.message}"
+    rescue SocketError, Errno::ECONNREFUSED => e
+      raise Error, "Connection failed: #{e.message}"
+    rescue StandardError => e
+      raise Error, "API request failed: #{e.message}"
+    end
+
+    def handle_response(response)
+      case response.code.to_i
+      when 200
+        JSON.parse(response.body)
+      when 401
+        raise Error, "Unauthorized: Invalid API key"
+      when 429
+        raise Error, "Rate limit exceeded"
+      else
+        begin
+          error_body = JSON.parse(response.body)
+          raise Error, error_body["error"]["message"] if error_body["error"]
+        rescue JSON::ParserError
+          # If we can't parse the error body, use the status text
+          raise Error, "API request failed with status #{response.code}: #{response.message}"
+        end
+      end
+    end
+  end
+end

data/lib/weatherxu/error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module WeatherXu
+  # Custom error class for WeatherXu API errors
+  class Error < StandardError
+    attr_reader :status_code, :error_code
+
+    def initialize(message, status_code: nil, error_code: nil)
+      super(message)
+      @status_code = status_code
+      @error_code = error_code
+    end
+  end
+end

data/lib/weatherxu/models.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "time"
+
+module WeatherXu
+  # Base class for API responses
+  class BaseModel
+    def initialize(data)
+      data.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+  end
+
+  # Weather data response
+  class WeatherData < BaseModel
+    attr_reader :success, :data
+
+    def initialize(data)
+      @success = data["success"]
+      @data = data["data"]
+
+      if @data
+        @data["alerts"] = @data["alerts"]&.map { |alert| Alert.new(alert) }
+        @data["currently"] = CurrentConditions.new(@data["currently"]) if @data["currently"]
+        @data["hourly"] = { "data" => @data["hourly"]["data"].map { |hour| HourlyCondition.new(hour) } } if @data["hourly"]
+        @data["daily"] = { "data" => @data["daily"]["data"].map { |day| DailyCondition.new(day) } } if @data["daily"]
+      end
+    end
+  end
+
+  # Historical weather data response
+  class HistoricalData < BaseModel
+    attr_reader :success, :data
+
+    def initialize(data)
+      @success = data["success"]
+      @data = data["data"]
+
+      if @data && @data["hourly"]
+        @data["hourly"] = {
+          "data" => @data["hourly"]["data"].map { |hour| HistoricalHourlyCondition.new(hour) }
+        }
+      end
+    end
+  end
+
+  # Weather alert information
+  class Alert < BaseModel
+    attr_reader :title, :description, :ends_at
+
+    def initialize(data)
+      super(data)
+      @ends_at = data["endsAt"]
+    end
+  end
+
+  # Current weather conditions
+  class CurrentConditions < BaseModel
+    attr_reader :apparent_temperature, :cloud_cover, :dew_point, :humidity,
+                :icon, :precip_intensity, :pressure, :temperature, :uv_index,
+                :visibility, :wind_direction, :wind_gust, :wind_speed
+
+    def initialize(data)
+      @apparent_temperature = data["apparentTemperature"]
+      @cloud_cover = data["cloudCover"]
+      @dew_point = data["dewPoint"]
+      @humidity = data["humidity"]
+      @icon = data["icon"]
+      @precip_intensity = data["precipIntensity"]
+      @pressure = data["pressure"]
+      @temperature = data["temperature"]
+      @uv_index = data["uvIndex"]
+      @visibility = data["visibility"]
+      @wind_direction = data["windDirection"]
+      @wind_gust = data["windGust"]
+      @wind_speed = data["windSpeed"]
+    end
+  end
+
+  # Hourly weather condition
+  class HourlyCondition < BaseModel
+    attr_reader :apparent_temperature, :cloud_cover, :dew_point, :forecast_start,
+                :humidity, :icon, :precip_intensity, :precip_probability, :pressure,
+                :temperature, :uv_index, :visibility, :wind_direction, :wind_gust,
+                :wind_speed
+
+    def initialize(data)
+      @apparent_temperature = data["apparentTemperature"]
+      @cloud_cover = data["cloudCover"]
+      @dew_point = data["dewPoint"]
+      @forecast_start = data["forecastStart"]
+      @humidity = data["humidity"]
+      @icon = data["icon"]
+      @precip_intensity = data["precipIntensity"]
+      @precip_probability = data["precipProbability"]
+      @pressure = data["pressure"]
+      @temperature = data["temperature"]
+      @uv_index = data["uvIndex"]
+      @visibility = data["visibility"]
+      @wind_direction = data["windDirection"]
+      @wind_gust = data["windGust"]
+      @wind_speed = data["windSpeed"]
+    end
+  end
+
+  # Historical hourly condition
+  class HistoricalHourlyCondition < BaseModel
+    attr_reader :apparent_temperature, :cloud_cover, :dew_point, :forecast_start,
+                :humidity, :icon, :precip_intensity, :pressure, :temperature,
+                :wind_direction, :wind_gust, :wind_speed
+
+    def initialize(data)
+      @apparent_temperature = data["apparentTemperature"]
+      @cloud_cover = data["cloudCover"]
+      @dew_point = data["dewPoint"]
+      @forecast_start = data["forecastStart"]
+      @humidity = data["humidity"]
+      @icon = data["icon"]
+      @precip_intensity = data["precipIntensity"]
+      @pressure = data["pressure"]
+      @temperature = data["temperature"]
+      @wind_direction = data["windDirection"]
+      @wind_gust = data["windGust"]
+      @wind_speed = data["windSpeed"]
+    end
+  end
+
+  # Daily weather condition
+  class DailyCondition < BaseModel
+    attr_reader :apparent_temperature_avg, :apparent_temperature_max,
+                :apparent_temperature_min, :cloud_cover, :dew_point_avg,
+                :dew_point_max, :dew_point_min, :forecast_end, :forecast_start,
+                :humidity, :icon, :moon_phase, :precip_intensity,
+                :precip_probability, :pressure, :sunrise_time, :sunset_time,
+                :temperature_avg, :temperature_max, :temperature_min,
+                :uv_index_max, :visibility, :wind_direction_avg, :wind_gust_avg,
+                :wind_gust_max, :wind_gust_min, :wind_speed_avg, :wind_speed_max,
+                :wind_speed_min
+
+    def initialize(data)
+      @apparent_temperature_avg = data["apparentTemperatureAvg"]
+      @apparent_temperature_max = data["apparentTemperatureMax"]
+      @apparent_temperature_min = data["apparentTemperatureMin"]
+      @cloud_cover = data["cloudCover"]
+      @dew_point_avg = data["dewPointAvg"]
+      @dew_point_max = data["dewPointMax"]
+      @dew_point_min = data["dewPointMin"]
+      @forecast_end = data["forecastEnd"]
+      @forecast_start = data["forecastStart"]
+      @humidity = data["humidity"]
+      @icon = data["icon"]
+      @moon_phase = data["moonPhase"]
+      @precip_intensity = data["precipIntensity"]
+      @precip_probability = data["precipProbability"]
+      @pressure = data["pressure"]
+      @sunrise_time = data["sunriseTime"]
+      @sunset_time = data["sunsetTime"]
+      @temperature_avg = data["temperatureAvg"]
+      @temperature_max = data["temperatureMax"]
+      @temperature_min = data["temperatureMin"]
+      @uv_index_max = data["uvIndexMax"]
+      @visibility = data["visibility"]
+      @wind_direction_avg = data["windDirectionAvg"]
+      @wind_gust_avg = data["windGustAvg"]
+      @wind_gust_max = data["windGustMax"]
+      @wind_gust_min = data["windGustMin"]
+      @wind_speed_avg = data["windSpeedAvg"]
+      @wind_speed_max = data["windSpeedMax"]
+      @wind_speed_min = data["windSpeedMin"]
+    end
+  end
+end

data/lib/weatherxu/version.rb

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

data/lib/weatherxu.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "weatherxu/version"
+require_relative "weatherxu/error"
+require_relative "weatherxu/models"
+require_relative "weatherxu/client"
+
+# WeatherXu module for accessing weather data
+module WeatherXu
+  class << self
+    # Create a new client instance
+    #
+    # @param api_key [String] Your WeatherXu API key
+    # @param units [String] Unit system ('metric' or 'imperial')
+    # @param timeout [Integer] Request timeout in seconds
+    # @return [Client] A new client instance
+    def new(api_key:, units: "metric", timeout: 10)
+      Client.new(api_key: api_key, units: units, timeout: timeout)
+    end
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: weatherxu
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- WeatherXu
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A Ruby SDK for accessing WeatherXu's weather data, including current
+  conditions, forecasts, and historical weather data.
+email:
+- support@weatherxu.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/weatherxu.rb
+- lib/weatherxu/client.rb
+- lib/weatherxu/error.rb
+- lib/weatherxu/models.rb
+- lib/weatherxu/version.rb
+homepage: https://weatherxu.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://weatherxu.com
+  source_code_uri: https://github.com/weatherxu/weatherxu-ruby
+  changelog_uri: https://github.com/weatherxu/weatherxu-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://weatherxu.com/documentation
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for WeatherXu's weather data API
+test_files: []