growatt 0.1.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 690f64562aa9bb8165ed9ddd859d5858c39d4a347c9a428997969881cb0dcfa4
-  data.tar.gz: 7a6236aa6d31d42ba90166dfbf3e64d5209e542eef2902186e394c7a708e41e4
+  metadata.gz: 77b696ab2333a1954a2e62dcacffea1cb9f1c4ba02f06e34001d90abc25ec4a2
+  data.tar.gz: ae2ce05b85d79cec90ca7beb35e820f0d2529b95c215fb2ebf88213c7c3d8b92
 SHA512:
-  metadata.gz: b02ff867b268c0d4ea7697a53e76cf4a6afb9245afb8ad34e5982f03d4789c6a3effc8518cc19d707d9bdad8483d95192136e9b40f04489c50568c7142b8c2f3
-  data.tar.gz: 4fd6b8ee8aafda44cf9ddada702f929a98c9a121ebaca71af70a786f6b8fb09fd884530a35542e1c1a2e4b1e6cff0178819656151449f6e017a117eaac2db018
+  metadata.gz: 433e4623b99df6514698821dbbd0ad319d736c47840b2c670f216b1bf9302f6cedede2c0f8ef9eb7bd02741f2d3ae0b8f179d72b14d69448852a7fc5eb6d219f
+  data.tar.gz: 2b6d7c7f0b69bace8f2b45ad838ff091e0af665ddc1dfae0c970a7bb0d692882428534eb706793102ce2524b00345f8eb02a9b771bb3dafc07dee2fa73c9c893

data/CHANGELOG.md

@@ -9,4 +9,8 @@
 ## [0.1.3] - 2024-05-30
 - fix api issues to get inverter data
 ## [0.1.4] - 2024-05-30
-- fix api issues where some api require correct Accept header 
+- fix api issues where some api require correct Accept header
+## [0.2.0] - 2024-06-03
+- rename method to reflect export limitations
+## [0.2.1] - 2025-03-19
+- add dcumenttion

data/README.md

@@ -1,5 +1,7 @@
 # Growatt API
 [![Version](https://img.shields.io/gem/v/growatt.svg)](https://rubygems.org/gems/growatt)
+[![Maintainability](https://api.codeclimate.com/v1/badges/60e7b62db0513a99ae4a/maintainability)](https://codeclimate.com/github/jancotanis/growatt/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/60e7b62db0513a99ae4a/test_coverage)](https://codeclimate.com/github/jancotanis/growatt/test_coverage)
 
 This is a wrapper for the Growatt rest API. Main objective is to turn inverter on/off. This has been testen with MOD-9000TL-X.
 
@@ -22,12 +24,12 @@ Or install it yourself as:
 
 ## Usage
 
-Before you start making the requests to API provide the endpoint and api key using the configuration wrapping.
+Before you start making the requests to API provide the username and password using with Shinephone app.
 
 ```ruby
 require 'growatt'
 require 'logger'
-
+TEST_LOGGER = './test.log'
 # use do block
 Growatt.configure do |config|
   config.username = ENV['GROWATT_USERNAME']
@@ -42,7 +44,7 @@ client.login
 ```
 
 ## Resources
-### Authentication
+### Authentication and configuration
 ```ruby
 # setup
 #
@@ -52,12 +54,40 @@ begin
   # turn invertor off
   client.turn_inverter('<serial_no>', false)
 rescue Growatt::AuthenticationError => e
-  puts "Error logging in growatt api"
+  puts "Error login to growatt api"
   puts e
 end
 ```
+### Read data
+
+```ruby
+# create client (don't forget to configure authentication)
+# get data for first inverter for first defined plant
+plants = client.plant_list
+plant_id = plants.data.first.plantId
+devices = client.inverter_list(plant_id)
+inverter = devices.first
 
+yymm = Time.now.strftime("%Y%m")
+puts "- loading period #{yymm}"
+data = client.inverter_data(inverter.deviceSn,Growatt::Timespan::MONTH,current_month)
 
+```
+
+### Control
+
+```ruby
+# continu from read data example above
+inverter = devices.first
+
+# turn inverter on/of
+client.turn_inverter(inverter.deviceSn, false)
+
+# or limit energy export
+client.export_limit(inverter.deviceSn,Growatt::ExportLimit::PERCENTAGE, 100)
+# allow energy export to grid
+client.export_limit(inverter.deviceSn,Growatt::ExportLimit::DISABLE)
+```
 
 ## Publishing
 
@@ -72,6 +102,7 @@ end
 5. Release
 ```
 > rake release
+```
 
 ## Contributing
 

data/Rakefile

@@ -6,14 +6,17 @@ require 'rake/testtask'
 
 Dotenv.load
 
-#system './bin/cc-test-reporter before-build'
+system './bin/cc-test-reporter before-build'
 Rake::TestTask.new(:test) do |t|
   t.libs << 'test'
   t.libs << 'lib'
   t.test_files = FileList['test/**/*_test.rb']
+  at_exit do
+    system './bin/cc-test-reporter after-build'
+  end
 end
 
 require 'rubocop/rake_task'
 RuboCop::RakeTask.new
 task default: %i[test rubocop]
-#system './bin/cc-test-reporter after-build'
+

data/lib/growatt/api.rb

@@ -1,15 +1,31 @@
-require "wrapi"
+# frozen_string_literal: true
+
+require 'wrapi'
 require File.expand_path('authorization', __dir__)
 require File.expand_path('connection', __dir__)
 
 module Growatt
-  # @private
+  # The `API` class is an internal component of the Growatt module.
+  # It is responsible for managing API configurations, connections, and authentication.
+  #
+  # This class should not be accessed directly. Instead, use `Growatt.client` to interact with the API.
+  #
   class API
-
-    # @private
+    # Attribute accessors for all valid configuration options.
+    #
+    # These options are defined in `WrAPI::Configuration::VALID_OPTIONS_KEYS`.
     attr_accessor *WrAPI::Configuration::VALID_OPTIONS_KEYS
 
-    # Creates a new API and copies settings from singleton
+    # Initializes a new `Growatt::API` instance.
+    #
+    # This method copies configuration settings from the Growatt module singleton and allows
+    # for optional overrides through the `options` parameter.
+    #
+    # @param options [Hash] Optional configuration overrides.
+    #
+    # @example Creating an API instance with custom options:
+    #   api = Growatt::API.new(user_agent: "CustomClient/1.0")
+    #
     def initialize(options = {})
       options = Growatt.options.merge(options)
       WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
@@ -17,6 +33,13 @@ module Growatt
       end
     end
 
+    # Retrieves the current API configuration as a hash.
+    #
+    # @return [Hash] A hash containing the current API configuration.
+    #
+    # @example Getting the current configuration:
+    #   api.config # => { endpoint: "https://server.growatt.com/", user_agent: "Ruby Growatt API client ..." }
+    #
     def config
       conf = {}
       WrAPI::Configuration::VALID_OPTIONS_KEYS.each do |key|
@@ -25,11 +48,12 @@ module Growatt
       conf
     end
 
+    # Includes required modules for making API requests, handling authentication,
+    # and establishing connections.
     include WrAPI::Connection
     include Connection
     include WrAPI::Request
     include WrAPI::Authentication
     include Authentication
-
   end
 end

data/lib/growatt/authorization.rb

@@ -1,36 +1,91 @@
+# frozen_string_literal: true
+
 require 'digest'
 require File.expand_path('error', __dir__)
 
 module Growatt
-  # Deals with authentication flow and stores it within global configuration
+  # Handles authentication flow and stores session data in the global configuration.
+  #
+  # This module provides methods for logging into the Growatt portal, hashing passwords, 
+  # and validating credentials.
+  #
   module Authentication
-
-    # Authorize to the Growatt portal
-    def login()
-      raise ConfigurationError, "Username/password not set" unless username || password
-      _password = hash_password(self.password) #unless is_password_hashed
+    # Logs in to the Growatt portal using the stored credentials.
+    #
+    # This method:
+    # - Validates that the username and password are set.
+    # - Hashes the password using MD5.
+    # - Sends a login request with the credentials.
+    # - Processes the server response.
+    #
+    # @raise [ConfigurationError] If username or password is missing.
+    # @raise [AuthenticationError] If authentication fails.
+    # @return [Hash] The login response data if successful.
+    #
+    # @example Logging in to Growatt:
+    #   client.login
+    #
+    def login
+      validate_credentials
+      _password = hash_password(self.password) # Hash password before sending
 
       _format = self.format
       self.format = 'x-www-form-urlencoded'
-      response = post('newTwoLoginAPI.do', {'userName': self.username, 'password': _password})
+      response = post('newTwoLoginAPI.do', { 'userName' => self.username, 'password' => _password })
       self.format = _format
-      data = response.body['back']
-      if data && data['success']
-        @login_data = data
-        data
-      else
-        raise AuthenticationError.new(data['error'])
-      end
+      process_response(response.body['back'])
     end
+
   private
+
+    # Hashes the given password using MD5.
+    #
+    # This method generates an MD5 hash of the password and modifies it by replacing
+    # every occurrence of '0' at even indices with 'c'.
+    #
+    # @param password [String] The plain-text password.
+    # @return [String] The modified MD5-hashed password.
+    #
+    # @example Hashing a password:
+    #   hash_password("mypassword") # => "5f4dcc3bcfcd204e074324a5e7565eaf"
+    #
     def hash_password(password)
       password_md5 = Digest::MD5.hexdigest(password.encode('utf-8'))
       (0...password_md5.length).step(2) do |i|
-        if password_md5[i] == '0'
-          password_md5[i] = 'c'
-        end
+        password_md5[i] = 'c' if password_md5[i] == '0'
       end
       password_md5
     end
+
+    # Validates that the username and password are set.
+    #
+    # @raise [ConfigurationError] If either credential is missing.
+    #
+    # @example Checking credentials before login:
+    #   validate_credentials # Raises ConfigurationError if missing
+    #
+    def validate_credentials
+      raise ConfigurationError, "Username/password not set" unless username && password
+    end
+
+    # Processes the authentication response.
+    #
+    # If authentication is successful, stores the login data. Otherwise, raises an error.
+    #
+    # @param data [Hash] The response data from the Growatt portal.
+    # @raise [AuthenticationError] If authentication fails.
+    # @return [Hash] The login data if authentication succeeds.
+    #
+    # @example Handling a successful login:
+    #   process_response({ "success" => true }) # Returns login data
+    #
+    def process_response(data)
+      if data && data['success']
+        @login_data = data
+        data
+      else
+        raise AuthenticationError.new(data['error'])
+      end
+    end
   end
 end

data/lib/growatt/client.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require File.expand_path('api', __dir__)
 require File.expand_path('const', __dir__)
 require File.expand_path('error', __dir__)
@@ -5,28 +7,56 @@ require File.expand_path('error', __dir__)
 module Growatt
   # Wrapper for the Growatt REST API
   #
-  # @see no API documentation, reverse engineered
+  # This class provides methods to interact with the Growatt API, including:
+  # - Retrieving plant and inverter data
+  # - Managing inverters (turning them on/off, updating settings)
+  # - Handling authentication and session data
+  #
+  # @note No official API documentation is available; this was reverse-engineered.
+  #
+  # @see Growatt::Authentication For authentication-related logic.
   class Client < API
-
+    # Initializes the Growatt API client.
+    #
+    # @param options [Hash] Additional options for the API client.
     def initialize(options = {})
       super(options)
     end
 
-    # access data returned from login
+    # Retrieves login session data.
+    #
+    # @return [Hash, nil] The login data stored in @login_data.
     def login_info
       @login_data
     end
-    def plant_list(user_id=nil)
-      user_id = login_info['user']['id'] unless user_id
-      _plant_list({'userId':user_id})
+
+    # Retrieves a list of plants associated with a user.
+    #
+    # @param user_id [String, nil] The user ID; if nil, it defaults to the logged-in user's ID.
+    # @return [Hash] The list of plants.
+    def plant_list(user_id = nil)
+      user_id ||= login_info['user']['id']
+      _plant_list({ 'userId': user_id })
     end
-    def plant_detail(plant_id,type=Timespan::DAY,date=Time.now)
-      _plant_detail( {
+
+    # Retrieves detailed information about a plant.
+    #
+    # @param plant_id [String] The plant ID.
+    # @param type [String] The timespan type (default: `Timespan::DAY`).
+    # @param date [Time] The date for the requested timespan (default: `Time.now`).
+    # @return [Hash] The plant details.
+    def plant_detail(plant_id, type = Timespan::DAY, date = Time.now)
+      _plant_detail({
         'plantId': plant_id,
         'type': type,
-        'date': timespan_date(type,date)
+        'date': timespan_date(type, date)
       })
     end
+
+    # Retrieves plant information.
+    #
+    # @param plant_id [String] The plant ID.
+    # @return [Hash] Plant information, including available devices.
     def plant_info(plant_id)
       _plant_info({
         'op': 'getAllDeviceList',
@@ -35,16 +65,28 @@ module Growatt
         'pageSize': 1
       })
     end
+
+    # Retrieves a list of devices in a plant.
+    #
+    # @param plant_id [String] The plant ID.
+    # @return [Array] A list of devices.
     def device_list(plant_id)
       plant_info(plant_id).deviceList
     end
 
+    # Retrieves a list of inverters in a plant.
+    #
+    # @param plant_id [String] The plant ID.
+    # @return [Array] A list of inverters.
     def inverter_list(plant_id)
       devices = device_list(plant_id)
-      devices.select { |device| 'inverter'.eql? device.deviceType  }
+      devices.select { |device| 'inverter'.eql? device.deviceType }
     end
 
-    # get data for invertor control
+    # Retrieves data for inverter control.
+    #
+    # @param inverter_id [String] The inverter's serial number.
+    # @return [Hash] The inverter's control data.
     def inverter_control_data(inverter_id)
       _inverter_api({
         'op': 'getMaxSetData',
@@ -52,109 +94,126 @@ module Growatt
       }).obj.maxSetBean
     end
 
-    def update_inverter_setting(serial_number,command,param_id,parameters)
+    # Updates an inverter's setting.
+    #
+    # @param serial_number [String] The inverter's serial number.
+    # @param command [String] The command to execute.
+    # @param param_id [String] The parameter ID.
+    # @param parameters [Array, Hash] The parameters to send.
+    # @return [Boolean] `true` if the update was successful, `false` otherwise.
+    def update_inverter_setting(serial_number, command, param_id, parameters)
       command_parameters = {
         'op': command,
         'serialNum': serial_number,
         'paramId': param_id
       }
-      # repeated values to hash { param1: value1 }
 
       parameters = parameters.map.with_index { |value, index| ["param#{index + 1}", value] }.to_h if parameters.is_a? Array
       self.format = 'x-www-form-urlencoded'
-      data = JSON.parse(post('newTcpsetAPI.do',command_parameters.merge(parameters)).body)
+      data = JSON.parse(post('newTcpsetAPI.do', command_parameters.merge(parameters)).body)
       self.format = :json
       data['success']
     end
 
-    # turn invertor on of off
-    def turn_inverter(serial_number,on=true)
-      onoff = (on ? Inverter::ON : Inverter::OFF )
-      update_inverter_setting(serial_number,'maxSetApi','max_cmd_on_off',[onoff])
+    # Turns an inverter on or off.
+    #
+    # @param serial_number [String] The inverter's serial number.
+    # @param on [Boolean] `true` to turn on, `false` to turn off.
+    # @return [Boolean] `true` if the operation was successful.
+    def turn_inverter(serial_number, on = true)
+      onoff = (on ? Inverter::ON : Inverter::OFF)
+      update_inverter_setting(serial_number, 'maxSetApi', 'max_cmd_on_off', [onoff])
     end
 
-    # check if invertor is turned on
+    # Checks if an inverter is turned on.
+    #
+    # @param serial_number [String] The inverter's serial number.
+    # @return [Boolean] `true` if the inverter is on, `false` otherwise.
     def inverter_on?(serial_number)
       status = inverter_control_data(serial_number)
       Inverter::ON.eql? status.max_cmd_on_off
     end
 
-    def export_limitation(serial_number,enable,value=nil)
-      if Inverter::DISABLE.eql? enable
+    # Sets export limit for an inverter.
+    #
+    # @param serial_number [String] The inverter's serial number.
+    # @param enable [String] `ExportLimit::DISABLE`, `ExportLimit::WATT`, or `ExportLimit::PERCENTAGE`.
+    # @param value [Numeric, nil] The export limit value (required unless disabled).
+    # @return [Boolean] `true` if the setting update was successful.
+    def export_limit(serial_number, enable, value = nil)
+      if ExportLimit::DISABLE.eql? enable
         params = [0]
       else
-        raise ArgumentError, "exportlimitation enable should be Inverter::WATT or Inverter::PERCENTAGE" unless [Inverter::WATT,Inverter::PERCENTAGE].include? enable
-        raise ArgumentError, "Value should be set for export limitation" unless value
+        validate_export_parameters(enable, value)
         params = [1, value, enable]
       end
-      update_inverter_setting(serial_number,'maxSetApi','backflow_setting',params)
+      update_inverter_setting(serial_number, 'maxSetApi', 'backflow_setting', params)
     end
 
-    # utility function to get date accordign timespan month/day
-    def timespan_date(timespan=Timespan::DAY,date=Time.now)
-      if Timespan::YEAR.eql? timespan
+    # Utility function to get a formatted date based on timespan.
+    #
+    # @param timespan [String] The timespan type (`Timespan::DAY`, `Timespan::MONTH`, `Timespan::YEAR`).
+    # @param date [Time] The date (default: `Time.now`).
+    # @return [String] The formatted date.
+    def timespan_date(timespan = Timespan::DAY, date = Time.now)
+      case timespan
+      when Timespan::YEAR
         date.strftime("%Y")
-      elsif Timespan::MONTH.eql? timespan
+      when Timespan::MONTH
         date.strftime("%Y-%m")
-      elsif Timespan::DAY.eql? timespan
+      when Timespan::DAY
         date.strftime("%Y-%m-%d")
       end
     end
 
+    # Retrieves inverter data based on timespan.
     #
-    # functions below are copied from python example code but not sure if these work with MOD9000 inverters
-    #
-    def inverter_data(inverter_id,type=Timespan::DAY,date=Time.now)
-      if Timespan::DAY.eql? type
-        operator = 'getInverterData_max'
-      elsif Timespan::MONTH.eql? type
-        operator = 'getMaxMonthPac'
-      elsif Timespan::YEAR.eql? type
-        operator = 'getMaxYearPac'
-      end
+    # @param inverter_id [String] The inverter's ID.
+    # @param type [String] The timespan type.
+    # @param date [Time] The date (default: `Time.now`).
+    # @return [Hash] The inverter data.
+    def inverter_data(inverter_id, type = Timespan::DAY, date = Time.now)
+      operator =
+        case type
+        when Timespan::DAY then 'getInverterData_max'
+        when Timespan::MONTH then 'getMaxMonthPac'
+        when Timespan::YEAR then 'getMaxYearPac'
+        end
+
       _inverter_api({
         'op': operator,
         'id': inverter_id,
         'type': 1,
-        'date': timespan_date(type,date)
-      })
-    end
-=begin
-    def inverter_detail(inverter_id)
-      _inverter_api({
-        'op': 'getInverterDetailData',
-        'inverterId': inverter_id
+        'date': timespan_date(type, date)
       })
     end
-    def inverter_detail_two(inverter_id)
-      _inverter_api({
-        'op': 'getInverterDetailData_two',
-        'inverterId': inverter_id
-      })
-    end
-=end
-    def update_mix_inverter_setting(serial_number, setting_type, parameters)
-      update_inverter_setting(serial_number,'mixSetApiNew',setting_type,parameters)
-    end
-    def update_ac_inverter_setting(serial_number, setting_type, parameters)
-      update_inverter_setting(serial_number,'spaSetApi',setting_type,parameters)
-    end
 
+    private
 
-  private
-    def self.api_endpoint(method,path)
-      # all records
-      self.send(:define_method, method) do |params = {}|
-        # return data result
-        get(path,params) do |request|
+    # Defines API endpoints dynamically.
+    #
+    # @param method [Symbol] The method name.
+    # @param path [String] The API endpoint.
+    def self.api_endpoint(method, path)
+      define_method(method) do |params = {}|
+        get(path, params) do |request|
           request.headers['Accept'] = "application/#{format}"
         end
       end
     end
+
     api_endpoint :_plant_list, 'PlantListAPI.do'
     api_endpoint :_plant_detail, 'PlantDetailAPI.do'
     api_endpoint :_inverter_api, 'newInverterAPI.do'
     api_endpoint :_plant_info, 'newTwoPlantAPI.do'
 
+    # Validates export limitation parameters.
+    def validate_export_parameters(enable, value)
+      unless [ExportLimit::WATT, ExportLimit::PERCENTAGE].include?(enable)
+        raise ArgumentError, "Export limitation must be ExportLimit::WATT or ExportLimit::PERCENTAGE"
+      end
+      raise ArgumentError, "Value is required" unless value
+      raise ArgumentError, "Value must be numeric" unless value.is_a? Numeric
+    end
   end
 end

data/lib/growatt/connection.rb

@@ -1,26 +1,45 @@
+# frozen_string_literal: true
+
 require 'faraday'
 require 'faraday-cookie_jar'
 
 module Growatt
-  # Create connection and use cookies for authentication tokens
+  # Handles HTTP connection setup and authentication management.
+  #
+  # This module establishes a Faraday connection to interact with the Growatt API,
+  # ensuring proper authentication via cookies and setting up required headers.
   module Connection
+    # Establishes a Faraday connection with appropriate middleware and settings.
+    #
+    # @return [Faraday::Connection] The configured Faraday connection instance.
+    # @raise [ConfigurationError] If the API endpoint is not defined.
     def connection
       raise ConfigurationError, "Option for endpoint is not defined" unless endpoint
 
       options = setup_options
       @connection ||= Faraday::Connection.new(options) do |connection|
+        # Enable cookie-based authentication
         connection.use :cookie_jar
 
+        # Handle HTTP response errors
         connection.use Faraday::Response::RaiseError
+
+        # Set up default Faraday adapter
         connection.adapter Faraday.default_adapter
+
+        # Configure authentication and request headers
         setup_authorization(connection)
         setup_headers(connection)
+
+        # Parse JSON responses automatically
         connection.response :json, content_type: /\bjson$/
+
+        # Ensure requests are URL-encoded
         connection.use Faraday::Request::UrlEncoded
 
+        # Configure logging if a logger is present
         setup_logger_filtering(connection, logger) if logger
       end
     end
-
   end
 end

data/lib/growatt/const.rb

@@ -1,26 +1,47 @@
+# frozen_string_literal: true
 
 module Growatt
+  # A base class for defining enumerations using constants.
+  #
+  # This class dynamically defines constants from an array of strings.
   class Enum
-      def self.enum(array)
-        array.each do |c|
-          const_set c,c
-        end
+    # Defines constants based on the provided array.
+    #
+    # @param array [Array<String>] The array of strings to be converted into constants.
+    def self.enum(array)
+      array.each do |c|
+        const_set c, c
       end
+    end
   end
 
+  # Represents different timespan options for data retrieval.
   class Timespan
+    # Hourly data timespan
     HOUR = 0
+    # Daily data timespan
     DAY = 1
+    # Monthly data timespan
     MONTH = 2
+    # Yearly data timespan
     YEAR = 3
   end
 
+  # Represents possible states for an inverter.
   class Inverter
+    # Inverter is turned on
     ON = "0101"
+    # Inverter is turned off
     OFF = "0000"
+  end
+
+  # Represents export limit settings for an inverter.
+  class ExportLimit
+    # Disables export limitation
     DISABLE = -1
+    # Export limit is set in watts
     WATT = 1
+    # Export limit is set in percentage
     PERCENTAGE = 0
   end
-
 end

data/lib/growatt/error.rb

@@ -1,12 +1,24 @@
+# frozen_string_literal: true
+
 module Growatt
 
-  # Generic error to be able to rescue all Hudu errors
+  # Base error class for all Growatt-related exceptions.
+  # Allows rescuing all Growatt-specific errors with `Growatt::GrowattError`.
   class GrowattError < StandardError; end
 
-  # Configuration returns error
+  # 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
 
-  # Issue authenticting
+  # 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,23 +1,29 @@
+# frozen_string_literal: true
+
 require 'uri'
 require 'json'
 
 module Growatt
-
-  # Defines HTTP request methods
+  # 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)
-        # data is at 'back'
+        # If the body is a Hash, return the 'back' key if it exists
         if body.is_a? Hash
-          if body['back']
-            body['back']
-          else
-            body
-          end
+          body['back'] || body
         else
-          # in some cases wrong contenttype is returned instead of app/json
+          # If the body is a String, parse it as JSON
           JSON.parse(body)
         end
       end

data/lib/growatt/version.rb

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

data/lib/growatt.rb

@@ -1,22 +1,57 @@
-require "wrapi"
+# 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
-  # https://openapi.growatt.com/ is an option but does not work with my account
-  DEFAULT_ENDPOINT = 'https://server.growatt.com/'.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]
+  # @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))
+    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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: growatt
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.1
 platform: ruby
 authors:
 - Janco Tanis
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-05-30 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: []
@@ -122,7 +120,6 @@ licenses:
 metadata:
   homepage_uri: https://rubygems.org/gems/growatt
   source_code_uri: https://github.com/jancotanis/growatt
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -137,8 +134,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: A Ruby wrapper for the Growatt APIs (readonly)
 test_files: []