growatt 0.2.0 → 0.2.1

data/lib/growatt/error.rb

@@ -1,12 +1,24 @@
-module Growatt
-
-  # Generic error to be able to rescue all Hudu errors
-  class GrowattError < StandardError; end
-
-  # Configuration returns error
-  class ConfigurationError < GrowattError; end
-
-  # Issue authenticting
-  class AuthenticationError < GrowattError; end
-
-end
+# frozen_string_literal: true
+
+module Growatt
+
+  # Base error class for all Growatt-related exceptions.
+  # Allows rescuing all Growatt-specific errors with `Growatt::GrowattError`.
+  class GrowattError < StandardError; end
+
+  # Raised when there is a configuration issue, such as missing or invalid settings.
+  #
+  # @example Raising a configuration error
+  #   raise Growatt::ConfigurationError, "Invalid API endpoint"
+  class ConfigurationError < GrowattError; end
+
+  # Raised when an authentication attempt fails.
+  #
+  # @example Handling authentication failure
+  #   begin
+  #     client.login
+  #   rescue Growatt::AuthenticationError => e
+  #     puts "Login failed: #{e.message}"
+  #   end
+  class AuthenticationError < GrowattError; end
+end

data/lib/growatt/pagination.rb

@@ -1,26 +1,32 @@
-require 'uri'
-require 'json'
-
-module Growatt
-
-  # Defines HTTP request methods
-  module RequestPagination
-
-    class DataPager < WrAPI::RequestPagination::DefaultPager
-
-      def self.data(body)
-        # data is at 'back'
-        if body.is_a? Hash
-          if body['back']
-            body['back']
-          else
-            body
-          end
-        else
-          # in some cases wrong contenttype is returned instead of app/json
-          JSON.parse(body)
-        end
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require 'uri'
+require 'json'
+
+module Growatt
+  # Provides pagination handling for API requests.
+  module RequestPagination
+    # Custom data pager for processing API responses.
+    # Inherits from `WrAPI::RequestPagination::DefaultPager` and extracts relevant data from responses.
+    class DataPager < WrAPI::RequestPagination::DefaultPager
+      # Extracts the relevant data from the API response body.
+      #
+      # @param body [String, Hash] The response body from an API request.
+      # @return [Hash] The parsed response data.
+      #
+      # @example Extracting data from a response
+      #   response = { "back" => { "items" => [...] } }
+      #   Growatt::RequestPagination::DataPager.data(response)
+      #   # => { "items" => [...] }
+      def self.data(body)
+        # If the body is a Hash, return the 'back' key if it exists
+        if body.is_a? Hash
+          body['back'] || body
+        else
+          # If the body is a String, parse it as JSON
+          JSON.parse(body)
+        end
+      end
+    end
+  end
+end

data/lib/growatt/version.rb

@@ -1,5 +1,5 @@
-# frozen_string_literal: true
-
-module Growatt
-  VERSION = '0.2.0'
-end
+# frozen_string_literal: true
+
+module Growatt
+  VERSION = '0.2.1'
+end

data/lib/growatt.rb

@@ -1,27 +1,62 @@
-require "wrapi"
-require File.expand_path('growatt/client', __dir__)
-require File.expand_path('growatt/version', __dir__)
-require File.expand_path('growatt/pagination', __dir__)
-
-module Growatt
-  extend WrAPI::Configuration
-  extend WrAPI::RespondTo
-
-  DEFAULT_UA = "Ruby Growatt API client #{Growatt::VERSION}".freeze
-  # https://openapi.growatt.com/ is an option but does not work with my account
-  DEFAULT_ENDPOINT = 'https://server.growatt.com/'.freeze
-  DEFAULT_PAGINATION = RequestPagination::DataPager
-  #
-  # @return [Growatt::Client]
-  def self.client(options = {})
-    Growatt::Client.new({ user_agent: DEFAULT_UA, endpoint: DEFAULT_ENDPOINT, pagination_class: DEFAULT_PAGINATION }.merge(options))
-  end
-
-  def self.reset
-    super
-    self.endpoint   = nil
-    self.user_agent = DEFAULT_UA
-    self.endpoint   = DEFAULT_ENDPOINT
-    self.pagination_class = DEFAULT_PAGINATION
-  end
-end
+# frozen_string_literal: true
+
+require 'wrapi'
+require File.expand_path('growatt/client', __dir__)
+require File.expand_path('growatt/version', __dir__)
+require File.expand_path('growatt/pagination', __dir__)
+
+# The `Growatt` module provides a Ruby client for interacting with the Growatt API.
+#
+# It extends `WrAPI::Configuration` for managing API settings and `WrAPI::RespondTo`
+# for handling API responses dynamically.
+#
+# The module allows you to create a client instance, configure API endpoints, and manage pagination settings.
+#
+# @example Creating a Growatt API client:
+#   client = Growatt.client(api_key: "your_api_key")
+#
+module Growatt
+  extend WrAPI::Configuration
+  extend WrAPI::RespondTo
+
+  # Default User-Agent string for API requests.
+  DEFAULT_UA = "Ruby Growatt API client #{Growatt::VERSION}".freeze
+
+  # Default API endpoint for Growatt services.
+  #
+  # Note: `https://openapi.growatt.com/` is an alternative, but it does not work with some accounts.
+  DEFAULT_ENDPOINT = 'https://server.growatt.com/'
+
+  # Default pagination class used for handling paginated API responses.
+  DEFAULT_PAGINATION = RequestPagination::DataPager
+
+  # Initializes and returns a new `Growatt::Client` instance.
+  #
+  # @param options [Hash] Configuration options for the client.
+  # @option options [String] :user_agent Custom user agent string.
+  # @option options [String] :endpoint Custom API endpoint.
+  # @option options [Class] :pagination_class Custom pagination class.
+  #
+  # @return [Growatt::Client] A new API client instance.
+  #
+  # @example Creating a client with custom options:
+  #   client = Growatt.client(user_agent: "MyCustomClient/1.0")
+  def self.client(options = {})
+    Growatt::Client.new({ 
+      user_agent: DEFAULT_UA, 
+      endpoint: DEFAULT_ENDPOINT, 
+      pagination_class: DEFAULT_PAGINATION 
+    }.merge(options))
+  end
+
+  # Resets the Growatt configuration to default values.
+  #
+  # This method restores the API endpoint, user agent, and pagination settings to their default values.
+  def self.reset
+    super
+    self.endpoint   = nil
+    self.user_agent = DEFAULT_UA
+    self.endpoint   = DEFAULT_ENDPOINT
+    self.pagination_class = DEFAULT_PAGINATION
+  end
+end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: growatt
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Janco Tanis
-autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-06-03 00:00:00.000000000 Z
+date: 2025-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: wrapi
@@ -94,7 +93,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
 email: gems@jancology.com
 executables: []
 extensions: []
@@ -116,16 +114,12 @@ files:
 - lib/growatt/error.rb
 - lib/growatt/pagination.rb
 - lib/growatt/version.rb
-- test/auth_test.rb
-- test/client_test.rb
-- test/test_helper.rb
 homepage: https://rubygems.org/gems/growatt
 licenses:
 - MIT
 metadata:
   homepage_uri: https://rubygems.org/gems/growatt
   source_code_uri: https://github.com/jancotanis/growatt
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -140,11 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A Ruby wrapper for the Growatt APIs (readonly)
-test_files:
-- test/auth_test.rb
-- test/client_test.rb
-- test/test_helper.rb
+test_files: []

data/test/auth_test.rb

@@ -1,20 +0,0 @@
-require 'dotenv'
-require 'logger'
-require 'test_helper'
-
-
-describe 'authentication' do
-
-  it '#1 use wrong username/password' do
-    assert_raises Growatt::AuthenticationError do
-      client = Growatt.client( { username: "xxx"+Growatt.username, password: Growatt.password } )
-      client.login
-      flunk( 'AuthenticationError expected' )
-    end
-  end
-  it '#2 use correct username/password' do
-    client = Growatt.client( { username: Growatt.username, password:Growatt.password } )
-    client.login
-  end
-
-end

data/test/client_test.rb

@@ -1,69 +0,0 @@
-require 'dotenv'
-require 'logger'
-require 'test_helper'
-
-def p m, o
-#  puts "#{m}: #{o.inspect}"
-end
-
-describe 'client' do
-  before do
-    @client = Growatt.client
-    @client.login
-  end
-
-  it '#1 GET info' do
-
-  end
-
-  it "#2 plant/device list" do
-    plants = @client.plant_list
-
-p "\n* plants", plants
-    plant_id = plants.data.first.plantId
-    assert plant_id, "plant_id should not be nil"
-
-    detail = @client.plant_detail(plant_id)
-p "\n* plant detail", detail
-    assert value(detail.plantData.plantId).must_equal(plant_id), 'correct plantId/structure'
-
-    plant_info = @client.plant_info(plant_id)
-p "\n* plant info:", plant_info
-
-    devices = @client.device_list(plant_id)
-p "\n* devices:", plant_info.deviceList
-    inverter = devices.first
-    # get data
-    data = @client.inverter_data(inverter.deviceSn,Growatt::Timespan::DAY,Time.now)
-    assert data, "Get day data by hour"
-    data = @client.inverter_data(inverter.deviceSn,Growatt::Timespan::MONTH,Time.now)
-    assert data, "Get month data by day"
-    data = @client.inverter_data(inverter.deviceSn,Growatt::Timespan::YEAR,Time.now)
-    assert data, "Get year data by month"
-puts "\n* Inverter data:"
-puts data.to_json
-
-    # turn device on
-    result = @client.turn_inverter(inverter.deviceSn,true)
-p "\n* turnon result:", result
-    is_on = @client.inverter_on?(inverter.deviceSn)
-
-    assert is_on, "Inverter should be on"
-    assert result, "inverter on should be success"
-  end
-  it "#3 export limitation parameters" do
-
-    assert_raises ArgumentError do
-      @client.export_limit('xxxx', 4)
-      flunk( 'ArgumentError expected, invalid limtation' )
-    end
-    assert_raises ArgumentError do
-      @client.export_limit('xxxx', Growatt::ExportLimit::WATT)
-      flunk( 'ArgumentError expected, no value given for WATTs' )
-    end
-    assert_raises ArgumentError do
-      @client.export_limit('xxxx',Growatt::ExportLimit::PERCENTAGE)
-      flunk( 'ArgumentError expected, no value given for PERCENTAGEs' )
-    end
-  end
-end

data/test/test_helper.rb

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-require 'simplecov'
-SimpleCov.start
-
-$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
-require 'minitest/autorun'
-require 'minitest/spec'
-
-require 'dotenv'
-require 'growatt'
-
-Dotenv.load
-
-TEST_LOGGER = 'test.log'
-
-File.delete(TEST_LOGGER) if File.exist?(TEST_LOGGER)
-
-Growatt.reset
-Growatt.configure do |config|
-  config.username = ENV['GROWATT_USERNAME']
-  config.password = ENV['GROWATT_PASSWORD']
-  config.logger = Logger.new(TEST_LOGGER)
-end