stekker_zaptec 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b93472771162eced218695ad47612b8d001d0b562669077af092de5ac5733d81
-  data.tar.gz: 78d184fb7979d966be2944c575a70444372555ea78101163f78c8565b5a90cec
+  metadata.gz: 033251f5675b4433989cfed337cc22e1271d37e5590b2a375964a3d207a0b5b4
+  data.tar.gz: f486808fc05a7d926cde6cbbb534d76ab5e74c93173f469a065fa5d5bbeedee6
 SHA512:
-  metadata.gz: d9930219d2b59aea5968498626b3289e40762a83afdfbd177605e4909ec9424cf588ca62f29b6162bce63803f4a4dd4a1ee06631451251cc547fb8678712bfc4
-  data.tar.gz: 5674b39478d6d644036f4ea5e85794e5331ef0440775d83ee21c46e36fd98e0f77e5b09d5e112f9c0238a7269fbf784a52449f08a55a05c9e8738bf870af2b07
+  metadata.gz: 0242033c65f7e6b86e4c24b82692b01697e07a3ac667a7aa551a9a61c1b195cdfc3b6d74e40c7883ea372321119aef753245a1bd63d755f9dbd40806ea3e1205
+  data.tar.gz: d54c276c0f1a24ef8dd8a9a76c9458cf1e3589481f2b627c575a68f238d580b3eda8d12cd51bcf3d9be23c325d8567d38d7d942206b1d1898dfa00417f3f9456

data/.github/workflows/ruby.yml

@@ -15,7 +15,7 @@ jobs:
         uses: actions/checkout@v3
 
       - name: Install Ruby and gems
-        uses: ruby/setup-ruby@ee2113536afb7f793eed4ce60e8d3b26db912da4
+        uses: ruby/setup-ruby@v1
         with:
           bundler-cache: true
 

data/.ruby-version

@@ -1 +1 @@
-3.0.2
+3.2.1

data/Gemfile

@@ -3,6 +3,7 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in zaptec.gemspec
 gemspec
 
+gem "gem-release", "~> 2.2"
 gem "jwt", "~> 2.6"
 gem "rake", "~> 13.0"
 gem "rspec", "~> 3.0"

data/Gemfile.lock

@@ -49,6 +49,7 @@ GEM
     faraday-retry (1.0.3)
     faraday_middleware (1.2.0)
       faraday (~> 1.0)
+    gem-release (2.2.2)
     hashdiff (1.0.1)
     i18n (1.12.0)
       concurrent-ruby (~> 1.0)
@@ -118,6 +119,7 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  gem-release (~> 2.2)
   jwt (~> 2.6)
   rake (~> 13.0)
   rspec (~> 3.0)

data/lib/stekker_zaptec.rb

@@ -4,11 +4,15 @@ require "active_model"
 require "active_support/all"
 
 require "zaptec/charger"
+require "zaptec/circuit"
 require "zaptec/client"
 require "zaptec/constants"
 require "zaptec/credentials"
 require "zaptec/errors"
+require "zaptec/installation"
+require "zaptec/installation_hierarchy"
 require "zaptec/meter_reading"
+require "zaptec/null_encryptor"
 require "zaptec/state"
 require "zaptec/version"
 

data/lib/zaptec/charger.rb

@@ -1,38 +1,14 @@
 module Zaptec
   class Charger
-    attr_reader :id,
-                :name,
-                :device_id,
-                :device_type,
-                :installation_name,
-                :installation_id
-
-    def initialize(
-      id:,
-      name:,
-      device_id:,
-      device_type:,
-      installation_name:,
-      installation_id:
-    )
-
-      @id = id
-      @name = name
-      @device_id = device_id
-      @device_type = device_type
-      @installation_name = installation_name
-      @installation_id = installation_id
+    def initialize(data)
+      @data = data.symbolize_keys
     end
 
-    def self.parse(data)
-      new(
-        id: data.fetch("Id"),
-        name: data.fetch("Name"),
-        device_id: data.fetch("DeviceId"),
-        device_type: data.fetch("DeviceType"),
-        installation_name: data.fetch("InstallationName"),
-        installation_id: data.fetch("InstallationId")
-      )
-    end
+    def id = @data.fetch(:Id)
+    def name = @data.fetch(:Name)
+    def device_id = @data.fetch(:DeviceId)
+    def device_type = @data.fetch(:DeviceType)
+    def installation_name = @data.fetch(:InstallationName)
+    def installation_id = @data.fetch(:InstallationId)
   end
 end

data/lib/zaptec/circuit.rb

@@ -0,0 +1,14 @@
+module Zaptec
+  class Circuit
+    def initialize(data)
+      @data = data.symbolize_keys
+    end
+
+    def id = @data.fetch(:Id)
+    def max_current = @data.fetch(:MaxCurrent)
+
+    def chargers
+      @chargers ||= @data.fetch(:Chargers).map { |data| Charger.new(data) }
+    end
+  end
+end

data/lib/zaptec/client.rb

@@ -1,10 +1,11 @@
 module Zaptec
   class Client
-    BASE_URI = "https://api.zaptec.com".freeze
+    BASE_URL = "https://api.zaptec.com".freeze
     USER_ROLE = 1
     OWNER_ROLE = 2
+    TOKENS_CACHE_KEY = "zaptec.auth.tokens".freeze
 
-    attr_reader :http_client, :credentials
+    attr_reader :credentials
 
     delegate :expired?,
              :access_token,
@@ -12,27 +13,35 @@ module Zaptec
              to: :credentials,
              prefix: true
 
-    def initialize(credentials: nil)
-      @credentials = credentials
+    def initialize(
+      username:,
+      password:,
+      token_cache: ActiveSupport::Cache::MemoryStore.new,
+      encryptor: NullEncryptor.new
+    )
+      @username = username
+      @password = password
+      @token_cache = token_cache
+      @encryptor = encryptor
+    end
 
-      @http_client = Faraday.new(url: BASE_URI) do |conn|
-        conn.request :json
-        conn.response :json
-        conn.response :raise_error
-      end
+    # https://zendesk.zaptec.com/hc/en-001/articles/6062673456657-Access-to-Installations-Authentication-for-Third-Parties#lookup-key-0-0
+    def grant_access_url(lookup_key:, partner_name:, redirect_url: nil, language: "en")
+      query = URI.encode_www_form(partnerName: partner_name, returnUrl: redirect_url, lang: language)
+      "https://portal.zaptec.com/#!/access/request/#{lookup_key}?#{query}"
     end
 
     # https://zaptec.com/downloads/ZapChargerPro_Integration.pdf
     def authorize(username:, password:)
       raise Errors::ParameterMissing if username.blank? || password.blank?
 
-      start = Time.zone.now
+      start = Time.current
 
-      response = http_client.post(
-        "#{BASE_URI}/oauth/token",
+      response = connection.post(
+        "#{BASE_URL}/oauth/token",
         {
-          username: username,
-          password: password,
+          username:,
+          password:,
           grant_type: "password"
         }.to_query,
         {
@@ -53,7 +62,19 @@ module Zaptec
       get("/api/chargers", { Roles: USER_ROLE | OWNER_ROLE })
         .body
         .fetch("Data")
-        .map { |data| Charger.parse(data) }
+        .map { |data| Charger.new(data) }
+    end
+
+    # https://api.zaptec.com/help/index.html#/Installation/get_api_installation__id_
+    def get_installation(installation_id)
+      get("/api/installation/#{installation_id}")
+        .then { |response| Installation.new(response.body) }
+    end
+
+    # https://api.zaptec.com/help/index.html#/Installation/get_api_installation__id__hierarchy
+    def get_installation_hierarchy(installation_id)
+      get("/api/installation/#{installation_id}/hierarchy")
+        .then { |response| InstallationHierarchy.new(response.body) }
     end
 
     # https://api.zaptec.com/help/index.html#/Charger/get_api_chargers__id__state
@@ -62,7 +83,7 @@ module Zaptec
         .body
         .to_h do |state|
           [
-            Constants.observation_state_id_to_name(state_id: state.fetch("StateId"), device_type: device_type),
+            Constants.observation_state_id_to_name(state_id: state.fetch("StateId"), device_type:),
             state.fetch("ValueAsString", nil)
           ]
         end
@@ -75,6 +96,22 @@ module Zaptec
 
     private
 
+    attr_reader :username, :password
+
+    def connection
+      Faraday.new(url: BASE_URL) do |conn|
+        conn.request :json
+        conn.response :json
+        conn.response :raise_error
+      end
+    end
+
+    def authenticated_connection
+      connection.tap do |conn|
+        conn.request :authorization, "Bearer", access_token
+      end
+    end
+
     # https://api.zaptec.com/help/index.html#/Charger/post_api_chargers__id__sendCommand__commandId_
     def send_command(charger_id, command)
       command_id = Constants.command_to_command_id(command)
@@ -83,29 +120,69 @@ module Zaptec
     end
 
     def get(endpoint, query = {})
-      require_valid_credentials!
+      with_error_handling do
+        authenticated_connection.get("#{BASE_URL}#{endpoint}", query)
+      end
+    end
 
-      http_client.get(
-        "#{BASE_URI}#{endpoint}",
-        query,
-        { Authorization: "Bearer #{credentials.access_token}" }
-      )
+    def post(endpoint, body: nil, query: nil)
+      with_error_handling do
+        authenticated_connection.post("#{BASE_URL}#{endpoint}", body) do |req|
+          req.params = query unless query.nil?
+        end
+      end
     end
 
-    def post(endpoint, body = nil)
-      require_valid_credentials!
+    def with_error_handling
+      token_refreshed ||= false
 
-      http_client.post(
-        "#{BASE_URI}#{endpoint}",
-        body,
-        { Authorization: "Bearer #{credentials.access_token}" }
-      )
+      yield
+    rescue Faraday::UnauthorizedError => e
+      if token_refreshed
+        raise Errors::RequestFailed.new("Request returned status #{e.response_status}", e.response)
+      else
+        refresh_access_token!
+        token_refreshed = true
+
+        retry
+      end
     rescue Faraday::Error => e
-      raise Errors::RequestFailed, "Request returned status #{e.response_status}"
+      raise Errors::RequestFailed.new("Request returned status #{e.response_status}", e.response)
+    end
+
+    def access_token
+      current_access_token
+        .then do |current|
+          if current.expired?
+            refresh_access_token!
+            current_access_token
+          else
+            current
+          end
+        end
+        .then(&:access_token)
     end
 
-    def require_valid_credentials!
-      raise Errors::Unauthorized if credentials.blank? || credentials.expired?
+    def current_access_token
+      encrypted_tokens = @token_cache.fetch(TOKENS_CACHE_KEY) do
+        @encryptor.encrypt(request_access_token.to_json, cipher_options: { deterministic: true })
+      end
+
+      plain_text_tokens = @encryptor.decrypt(encrypted_tokens)
+      Credentials.parse(JSON.parse(plain_text_tokens))
     end
+
+    def refresh_access_token!
+      @token_cache.write(
+        TOKENS_CACHE_KEY,
+        @encryptor.encrypt(request_access_token.to_json, cipher_options: { deterministic: true }),
+        expires_in: 1.day
+      )
+    rescue Faraday::Error => e
+      raise Errors::RequestFailed.new("Request returned status #{e.response_status}", e.response)
+    end
+
+    # https://developer.easee.cloud/reference/post_api-accounts-login
+    def request_access_token = authorize(username:, password:)
   end
 end

data/lib/zaptec/constants.rb

@@ -21,6 +21,22 @@ module Zaptec
           .fetch(command.to_s) { raise "Unknown command '#{command}'" }
       end
 
+      def country_id_to_country_code(country_id)
+        return if country_id.nil?
+
+        constants
+          .fetch("Countries")
+          .fetch(country_id)
+          .fetch("Code")
+      end
+
+      def network_type_to_name(network_type)
+        constants
+          .fetch("NetworkTypes")
+          .detect { |_name, type| type == network_type }
+          .then { |name, _type| name }
+      end
+
       private
 
       def device_type_observation_ids(device_type)

data/lib/zaptec/credentials.rb

@@ -10,5 +10,16 @@ module Zaptec
     def expired?(at = Time.zone.now)
       expires_at.nil? || at >= expires_at
     end
+
+    def self.parse(data)
+      new(
+        data.fetch("access_token"),
+        Time.zone.at(data.fetch("expires_at"))
+      )
+    end
+
+    def as_json(*)
+      super.merge("expires_at" => expires_at.to_i)
+    end
   end
 end

data/lib/zaptec/errors.rb

@@ -3,7 +3,14 @@ module Zaptec
     class Base < StandardError; end
     class ParameterMissing < Base; end
     class Unauthorized < Base; end
-    class RequestFailed < Base; end
+    class RequestFailed < Base
+      attr_reader :response
+
+      def initialize(message, response = nil)
+        @response = response
+        super(message)
+      end
+    end
     class AuthorizationFailed < Base; end
   end
 end

data/lib/zaptec/installation.rb

@@ -0,0 +1,15 @@
+module Zaptec
+  class Installation
+    def initialize(data)
+      @data = data.deep_symbolize_keys
+    end
+
+    def id = @data.fetch(:Id)
+    def address = @data[:Address]
+    def zip_code = @data[:ZipCode]
+    def city = @data[:City]
+    def latitude = @data[:Latitude]
+    def country_code = Constants.country_id_to_country_code(@data[:CountryId])
+    def longitude = @data[:Longitude]
+  end
+end

data/lib/zaptec/installation_hierarchy.rb

@@ -0,0 +1,15 @@
+module Zaptec
+  class InstallationHierarchy
+    def initialize(data)
+      @data = data.deep_symbolize_keys
+    end
+
+    def id = @data.fetch(:Id)
+    def name = @data.fetch(:Name)
+    def network_type = Constants.network_type_to_name(@data.fetch(:NetworkType))
+
+    def circuits
+      @circuits ||= @data.fetch(:Circuits).map { |data| Circuit.new(data) }
+    end
+  end
+end

data/lib/zaptec/null_encryptor.rb

@@ -0,0 +1,17 @@
+module Zaptec
+  # rubocop:disable Lint/UnusedMethodArgument
+  class NullEncryptor
+    def encrypt(clear_text, key_provider: nil, cipher_options: {})
+      clear_text
+    end
+
+    def decrypt(encrypted_text, key_provider: nil, cipher_options: {})
+      encrypted_text
+    end
+
+    def encrypted?(_text)
+      false
+    end
+  end
+  # rubocop:enable Lint/UnusedMethodArgument
+end

data/lib/zaptec/state.rb

@@ -20,7 +20,7 @@ module Zaptec
     def online? = @data.fetch(:IsOnline).to_i.positive?
 
     def meter_reading
-      @meter_reading ||= MeterReading.new(reading_kwh: total_charge_power_session, timestamp: Time.zone.now)
+      @meter_reading ||= MeterReading.new(reading_kwh: total_charge_power, timestamp: Time.zone.now)
     end
 
     private

data/lib/zaptec/version.rb

@@ -1,3 +1,3 @@
 module Zaptec
-  VERSION = "1.1.1".freeze
+  VERSION = "1.2.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: stekker_zaptec
 version: !ruby/object:Gem::Version
-  version: 1.1.1
+  version: 1.2.0
 platform: ruby
 authors:
 - Team Stekker
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-20 00:00:00.000000000 Z
+date: 2023-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -87,11 +87,15 @@ files:
 - data/constants.json
 - lib/stekker_zaptec.rb
 - lib/zaptec/charger.rb
+- lib/zaptec/circuit.rb
 - lib/zaptec/client.rb
 - lib/zaptec/constants.rb
 - lib/zaptec/credentials.rb
 - lib/zaptec/errors.rb
+- lib/zaptec/installation.rb
+- lib/zaptec/installation_hierarchy.rb
 - lib/zaptec/meter_reading.rb
+- lib/zaptec/null_encryptor.rb
 - lib/zaptec/state.rb
 - lib/zaptec/version.rb
 - zaptec.gemspec
@@ -110,14 +114,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.2
+      version: 3.2.1
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.22
+rubygems_version: 3.4.6
 signing_key:
 specification_version: 4
 summary: Connect to your Zaptec charger