enphase-client 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7e8f4ce942ac46d32bb544eab1d0df466f948f989bf6860a17ea64e92125db96
+  data.tar.gz: acf020736382a8e3678ace7fd43f431a763e66b47a54bf012e9eb16b5cae77f3
+SHA512:
+  metadata.gz: 673e424dcada9328bed969184b1b36147f9e6bef4e7e20fe3c4ec189f4b58cf02956324ae01f505d5524a99bd7e221ed4a9633d2b65694b005b2c291c8d4199d
+  data.tar.gz: 750d1a2605e6c7c86e680e1f7a7494519050888f7221505efd1af2c3ed745b2cc7c5c004ab434eb8971215710a9a1ead0ac3c014309e1acb5e4bb021a7a022cb

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in cocina-models.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,49 @@
+PATH
+  remote: .
+  specs:
+    enphase-client (0.0.1)
+      faraday
+      faraday_middleware
+      json
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    faraday (1.9.3)
+      faraday-em_http (~> 1.0)
+      faraday-em_synchrony (~> 1.0)
+      faraday-excon (~> 1.1)
+      faraday-httpclient (~> 1.0)
+      faraday-multipart (~> 1.0)
+      faraday-net_http (~> 1.0)
+      faraday-net_http_persistent (~> 1.0)
+      faraday-patron (~> 1.0)
+      faraday-rack (~> 1.0)
+      faraday-retry (~> 1.0)
+      ruby2_keywords (>= 0.0.4)
+    faraday-em_http (1.0.0)
+    faraday-em_synchrony (1.0.0)
+    faraday-excon (1.1.0)
+    faraday-httpclient (1.0.1)
+    faraday-multipart (1.0.3)
+      multipart-post (>= 1.2, < 3)
+    faraday-net_http (1.0.1)
+    faraday-net_http_persistent (1.2.0)
+    faraday-patron (1.0.0)
+    faraday-rack (1.0.0)
+    faraday-retry (1.0.3)
+    faraday_middleware (1.2.0)
+      faraday (~> 1.0)
+    json (2.6.1)
+    multipart-post (2.1.1)
+    ruby2_keywords (0.0.5)
+
+PLATFORMS
+  x86_64-darwin-18
+  x86_64-darwin-19
+
+DEPENDENCIES
+  enphase-client!
+
+BUNDLED WITH
+   2.3.4

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2022 Peter Mangiafico
+
+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,136 @@
+# Enlighten Ruby
+
+This is a lightweight Ruby wrapper around the Enphase Enlighten API available at https://developer.enphase.com/
+
+I am not affiliated with Enphase, this is just a convenience wrapper around their published API to make it easy to use in a Ruby app.  To use it, you will need to register an app to obtain an API key (or use your own existing API key).  You will also need to get authorization to connect a user's system (even if your own) using the instructions provided at https://developer.enphase.com/docs/quickstart.html
+
+## Usage
+
+1. Add the gem to your Gemfile.
+2. Require if neeed.
+3. Once you have an API key and an authorized user ID, you can instantiate the client and make API calls.  You will usually need the system ID you are interested in for most calls.  There is a call to fetch system IDs that you have access to. Responses are ruby hash objects.
+4. Dates returned by the API can be in one of two formats, UNIX Epoch or ISO8601.  The client defaults to ISO8601, but you can specify epoch if you want when instantiating the client.
+
+In Gemfile:
+```
+gem 'enphase-client'
+```
+
+In app:
+```
+require 'enphase-client'
+client = Enphase::Client.new(api_key: YOUR_API_KEY, user_id: AUTHORIZED_USER_ID)
+
+OR
+
+client = Enphase::Client.new(api_key: YOUR_API_KEY, user_id: AUTHORIZED_USER_ID, datetime_format: 'epoch') # for epoch datetimes
+
+result = client.stats(system_id: SYSTEM_ID)
+result
+ =>
+3.0.3 :006 > c.stats(system_id: '2599884')
+ =>
+{"system_id"=>2599884,
+ "total_devices"=>19,
+ "intervals"=>
+  [{"end_at"=>"2022-01-21T07:20:00-08:00", "devices_reporting"=>19, "powr"=>3, "enwh"=>0},
+   {"end_at"=>"2022-01-21T07:25:00-08:00", "devices_reporting"=>19, "powr"=>7, "enwh"=>1},
+   {"end_at"=>"2022-01-21T07:30:00-08:00", "devices_reporting"=>19, "powr"=>29, "enwh"=>2},
+   {"end_at"=>"2022-01-21T07:35:00-08:00", "devices_reporting"=>19, "powr"=>46, "enwh"=>4},
+   {"end_at"=>"2022-01-21T07:40:00-08:00", "devices_reporting"=>19, "powr"=>75, "enwh"=>6},
+   {"end_at"=>"2022-01-21T07:45:00-08:00", "devices_reporting"=>19, "powr"=>98, "enwh"=>8},
+   {"end_at"=>"2022-01-21T07:50:00-08:00", "devices_reporting"=>19, "powr"=>119, "enwh"=>10},
+   {"end_at"=>"2022-01-21T07:55:00-08:00", "devices_reporting"=>19, "powr"=>132, "enwh"=>11},
+   {"end_at"=>"2022-01-21T08:00:00-08:00", "devices_reporting"=>19, "powr"=>151, "enwh"=>13},
+   {"end_at"=>"2022-01-21T08:05:00-08:00", "devices_reporting"=>19, "powr"=>169, "enwh"=>14},
+   {"end_at"=>"2022-01-21T08:10:00-08:00", "devices_reporting"=>19, "powr"=>187, "enwh"=>16},
+   {"end_at"=>"2022-01-21T08:15:00-08:00", "devices_reporting"=>19, "powr"=>214, "enwh"=>18},
+   {"end_at"=>"2022-01-21T08:20:00-08:00", "devices_reporting"=>19, "powr"=>233, "enwh"=>19},
+   {"end_at"=>"2022-01-21T08:25:00-08:00", "devices_reporting"=>19, "powr"=>252, "enwh"=>21},
+   {"end_at"=>"2022-01-21T08:30:00-08:00", "devices_reporting"=>19, "powr"=>282, "enwh"=>24},
+   {"end_at"=>"2022-01-21T08:35:00-08:00", "devices_reporting"=>19, "powr"=>321, "enwh"=>27},
+   {"end_at"=>"2022-01-21T08:40:00-08:00", "devices_reporting"=>19, "powr"=>380, "enwh"=>32},
+   {"end_at"=>"2022-01-21T08:45:00-08:00", "devices_reporting"=>19, "powr"=>460, "enwh"=>38},
+   {"end_at"=>"2022-01-21T08:50:00-08:00", "devices_reporting"=>19, "powr"=>560, "enwh"=>47},
+   {"end_at"=>"2022-01-21T08:55:00-08:00", "devices_reporting"=>19, "powr"=>654, "enwh"=>55},
+   {"end_at"=>"2022-01-21T09:00:00-08:00", "devices_reporting"=>19, "powr"=>720, "enwh"=>60},
+   {"end_at"=>"2022-01-21T09:05:00-08:00", "devices_reporting"=>19, "powr"=>760, "enwh"=>63},
+   {"end_at"=>"2022-01-21T09:10:00-08:00", "devices_reporting"=>19, "powr"=>807, "enwh"=>67},
+   {"end_at"=>"2022-01-21T09:15:00-08:00", "devices_reporting"=>19, "powr"=>852, "enwh"=>71},
+   {"end_at"=>"2022-01-21T09:20:00-08:00", "devices_reporting"=>19, "powr"=>865, "enwh"=>72},
+   {"end_at"=>"2022-01-21T09:25:00-08:00", "devices_reporting"=>19, "powr"=>846, "enwh"=>71},
+   {"end_at"=>"2022-01-21T09:30:00-08:00", "devices_reporting"=>19, "powr"=>847, "enwh"=>71},
+   {"end_at"=>"2022-01-21T09:35:00-08:00", "devices_reporting"=>19, "powr"=>936, "enwh"=>78},
+   {"end_at"=>"2022-01-21T09:40:00-08:00", "devices_reporting"=>19, "powr"=>1054, "enwh"=>88},
+   {"end_at"=>"2022-01-21T09:45:00-08:00", "devices_reporting"=>19, "powr"=>1164, "enwh"=>97},
+   {"end_at"=>"2022-01-21T09:50:00-08:00", "devices_reporting"=>19, "powr"=>1315, "enwh"=>110},
+   {"end_at"=>"2022-01-21T09:55:00-08:00", "devices_reporting"=>19, "powr"=>1464, "enwh"=>122},
+   {"end_at"=>"2022-01-21T10:00:00-08:00", "devices_reporting"=>19, "powr"=>1587, "enwh"=>132},
+   {"end_at"=>"2022-01-21T10:05:00-08:00", "devices_reporting"=>19, "powr"=>1759, "enwh"=>147},
+   {"end_at"=>"2022-01-21T10:10:00-08:00", "devices_reporting"=>19, "powr"=>1967, "enwh"=>164},
+   {"end_at"=>"2022-01-21T10:15:00-08:00", "devices_reporting"=>19, "powr"=>2107, "enwh"=>176},
+   {"end_at"=>"2022-01-21T10:20:00-08:00", "devices_reporting"=>19, "powr"=>2216, "enwh"=>185},
+   {"end_at"=>"2022-01-21T10:25:00-08:00", "devices_reporting"=>19, "powr"=>2364, "enwh"=>197},
+   {"end_at"=>"2022-01-21T10:30:00-08:00", "devices_reporting"=>19, "powr"=>2535, "enwh"=>211},
+   {"end_at"=>"2022-01-21T10:35:00-08:00", "devices_reporting"=>19, "powr"=>2645, "enwh"=>220},
+   {"end_at"=>"2022-01-21T10:40:00-08:00", "devices_reporting"=>19, "powr"=>2685, "enwh"=>224},
+   {"end_at"=>"2022-01-21T10:45:00-08:00", "devices_reporting"=>19, "powr"=>2802, "enwh"=>234},
+   {"end_at"=>"2022-01-21T10:50:00-08:00", "devices_reporting"=>19, "powr"=>2944, "enwh"=>245},
+   {"end_at"=>"2022-01-21T10:55:00-08:00", "devices_reporting"=>19, "powr"=>2988, "enwh"=>249},
+   {"end_at"=>"2022-01-21T11:00:00-08:00", "devices_reporting"=>19, "powr"=>2997, "enwh"=>250},
+   {"end_at"=>"2022-01-21T11:05:00-08:00", "devices_reporting"=>19, "powr"=>3070, "enwh"=>256},
+   {"end_at"=>"2022-01-21T11:10:00-08:00", "devices_reporting"=>19, "powr"=>3144, "enwh"=>262}],
+ "meta"=>
+  {"status"=>"normal",
+   "last_report_at"=>"2022-01-21T11:16:29-08:00",
+   "last_energy_at"=>"2022-01-21T11:12:58-08:00",
+   "operational_at"=>"2014-01-01T10:29:53-08:00"}}
+```
+
+## Available API calls in the client
+
+These are just mapped 1:1 for the calls shown at https://developer.enphase.com/docs
+
+If the call succeeds, you will get a Ruby hash out that maps exactly the JSON response described in the documents.
+If the call fails, you will get a `Enphase::ClientError` error raised with a status code and message.  You should handle this exception in your app to provide error handling.
+
+If optional parameters can be passed for these API calls, you can add them has keyword arguments to the method (a couple examples shown below).  Note that the `start_at` and `end_at` interval parameters that can be passed to many of the
+calls are UNIX epoch times, regardless of the return date format specified.  You can convert ruby dates to UNIX epoch:
+
+```
+require 'time'
+puts Time.parse('2022-01-15T10:20:00-08:00').to_i
+=> 1642270800
+```
+
+1. Stats: https://developer.enphase.com/docs#stats
+
+```
+result = client.stats(system_id: SYSTEM_ID)
+
+# with optional intervals parameters
+result = client.stats(system_id: SYSTEM_ID, start_at: '1642270800', end_at: '1642278000')
+
+```
+
+2. Summary: https://developer.enphase.com/docs#summary
+
+```
+result = client.summary(system_id: SYSTEM_ID)
+```
+
+3. Inverters summary: https://developer.enphase.com/docs#inverters_summary_by_envoy_or_site
+
+```
+result = client.inverters(system_id: SYSTEM_ID)
+```
+
+4. Systems: https://developer.enphase.com/docs#index
+
+```
+result = client.systems
+```
+
+## License
+
+This code is provided under an MIT License.  https://opensource.org/licenses/MIT

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'enphase/client'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/enphase-client.gemspec

@@ -0,0 +1,17 @@
+Gem::Specification.new do |s|
+  s.name        = 'enphase-client'
+  s.version     = '0.0.1'
+  s.summary     = "A Ruby gem wrapper for the Enphase Enlighten Systems API"
+  s.description = "See https://developer.enphase.com/ for information on how to get an API key and authorize access for a user."
+  s.authors     = ["Peter Mangiafico"]
+  s.email       = 'peter@mangiafico.org'
+  s.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  s.add_dependency 'faraday'
+  s.add_dependency 'faraday_middleware'
+  s.add_dependency 'json'
+
+  s.homepage      = 'https://rubygems.org/gems/enphase-client'
+  s.license       = 'MIT'
+end

data/lib/enphase/client.rb

@@ -0,0 +1,63 @@
+require 'faraday'
+require 'faraday/net_http'
+require 'faraday_middleware'
+require 'json'
+
+module Enphase
+  class ClientError < StandardError; end
+end
+
+module Enphase
+  class Client
+    attr_reader :api_key, :user_id, :datetime_format
+
+    # datetime format can be 'iso8601' or 'epoch', defaults to 'iso8601'
+    def initialize(api_key:, user_id:, datetime_format: 'iso8601')
+      @api_key = api_key
+      @user_id = user_id
+      @datetime_format = datetime_format
+    end
+
+    # Stats Endpoint
+    def stats(system_id:, **params)
+      get_json(url: "systems/#{system_id}/stats", params: params)
+    end
+
+    # Summary Endpoint
+    def summary(system_id:, **params)
+      get_json(url: "systems/#{system_id}/summary", params: params)
+    end
+
+    # Inverters Summary Endpoint
+    def inverters(site_id:)
+      get_json(url: 'systems/inverters_summary_by_envoy_or_site', params: {site_id: site_id})
+    end
+
+    # Index Endpoint
+    def systems(**params)
+      get_json(url: 'systems', params: params)
+    end
+
+    private
+    def get_json(url:, params: {})
+      conn = Faraday.new(
+          url: "#{base_url}/#{url}",
+          params: params.merge({key: api_key, user_id: user_id, datetime_format: datetime_format})
+          ) do |f|
+            f.request :json # encode req bodies as JSON and automatically set the Content-Type header
+            f.response :json # decode response bodies as JSON
+            f.adapter :net_http # adds the adapter to the connection
+      end
+      response = conn.get
+      if response.success?
+        response.body
+      else
+        raise Enphase::ClientError.new("API returned status #{response.status}: #{response.reason_phrase}")
+      end
+    end
+
+    def base_url
+      'https://api.enphaseenergy.com/api/v2'
+    end
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: enphase-client
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Peter Mangiafico
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2022-02-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: See https://developer.enphase.com/ for information on how to get an API
+  key and authorize access for a user.
+email: peter@mangiafico.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- bin/console
+- bin/setup
+- enphase-client.gemspec
+- lib/enphase/client.rb
+homepage: https://rubygems.org/gems/enphase-client
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.6
+signing_key:
+specification_version: 4
+summary: A Ruby gem wrapper for the Enphase Enlighten Systems API
+test_files: []