gaapi 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 585053bbca2711362dde0579853b07716b1e8b5f60443a0060d49b348cf787f3
-  data.tar.gz: 4d200b10dda8d3b22314cfc3b8b0edc92990ed1b9c38fd7b2d6cadc231aa2f6e
+  metadata.gz: c22fc4035ce9aa902bd074f1781e502b26912a8793716ee02076dbfb0a5f5ae8
+  data.tar.gz: e8b76b26a8d77b4a5529db7f4565d4c33073f88f60cd208c2a3d725d74db43bc
 SHA512:
-  metadata.gz: 0f3262f52f469928c1d233742179b894531fa005e4bf7c19ae51ce0c6f55c9313486d00865935a52282300a469a4dad2c4523d86d0acd6e566c2833582f448e0
-  data.tar.gz: d1f7b1722c569713746245719e521d803021860c641c77f0b7746d929b4dc27d006aedecf957bee0c274873054fec4d7a954ffa0a9e3e6db7953e4f04ad1a41b
+  metadata.gz: 26335da752592ddedc4483b91a9da1a0bb8e7217971659513fb5eb5bb61f170639359232650f9a203bc3e57d165bb5371050a0f967e7569dd744990c1b4c92d3
+  data.tar.gz: 137a10c00dcf6fe42ecda4ae13dec4625fe484e7f155d4327b5653b756700f45377028b992bb749c170ad4552e8cfb80ac16bb8544f6a28ef249279dee41397e

data/CHANGELOG.md

@@ -1,4 +1,4 @@
-## [Pending Release][0.5.0]
+## [Pending Release][0.6.0]
 
 ### Breaking changes
 
@@ -12,6 +12,17 @@
 
 * Your contribution here!
 
+## [0.5.0][](2018-12-07)
+
+### Breaking changes
+
+* Removed an unused parameter from Report.new.
+
+### New features
+
+* Added `is_data_golden` and `next_page_token` methods to `Row` and `Report`.
+* Improved the Yard documentation.
+
 ## [0.4.3][](2018-11-28)
 
 ### Bugfixes
@@ -85,6 +96,7 @@
 * N/A.
 
 [Pending Release]: https://github.com/weenhanceit/gaapi/compare/v0.4.3...HEAD
+[0.5.0]: https://github.com/weenhanceit/gaapi/compare/v0.4.3...v0.5.0
 [0.4.3]: https://github.com/weenhanceit/gaapi/compare/v0.4.2...v0.4.3
 [0.4.2]: https://github.com/weenhanceit/gaapi/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/weenhanceit/gaapi/compare/v0.4.0...v0.4.1

data/lib/gaapi/report.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
 
 module GAAPI
-  # A single report from a query to Google Analytics
+  # A single report from a query to Google Analytics, with convenient methods
+  # to access the dimensions and metrics returned.
   class Report
-    # An array of the dimensions, in the order that they appear in the response.
+    # An array of the dimensions, in the order that they appear in the report.
     def dimensions
       report["columnHeader"]["dimensions"] || []
     end
@@ -14,33 +15,56 @@ module GAAPI
     end
 
     # An array of the dimensions first and then the metrics, in the order that
-    # they appear in the response.
+    # they appear in the report.
     def headers
       dimensions + metrics
     end
 
-    def initialize(response, report)
-      @response = response
-      @report = report
+    # Initialize a new Report.
+    # @param report [JSON source, Hash] If a Hash, assume it's a valid report
+    #   from a Google Analytics query, and use it as the report.
+    #   Otherwise, attempt to parse it with `JSON.parse`.
+    #   No checking is done on the input to ensure that it's a valid response
+    #   from a Google Analytics query, so subsequent calls to the methods on the
+    #   object returned from `Report.new` may fail in spectacular ways.
+    def initialize(report)
+      @report = report.is_a?(Hash) ? report : JSON.parse(report)
     end
+    # The report as a Ruby Hash, with String keys. It's typically much more
+    # convenient to use the `#rows` method, and the methods on `Row` on each
+    # instance of the a Row.
     attr_reader :report
 
-    # An array of the metric names, in the order that they appear in the response.
+    # Return if the data is golden, meaning it won't change if the query is re-run
+    # at a later time. The is a lag between the end of a date period and when
+    # Google Analytics has completely consolidated all the tracking data.
+    def is_data_golden
+      report["data"]["isDataGolden"]
+    end
+
+    # The metric type of the i'th metric in the report.
     def metric_type(i)
       report["columnHeader"]["metricHeader"]["metricHeaderEntries"][i]["type"]
     end
 
-    # An array of the metric names, in the order that they appear in the response.
+    # An array of the metric names, in the order that they appear in the report.
     def metrics
       report["columnHeader"]["metricHeader"]["metricHeaderEntries"].map { |metric| metric["name"] }
     end
 
+    # Return the nextPageToken, if any, indicating that the query exceeded
+    # the maximum number of rows allowed in a single response, and that the client
+    # has to ask for the rest of the data.
+    def next_page_token
+      report["nextPageToken"]
+    end
+
     # The data rows in the report.
     def rows
       report["data"]["rows"].map { |row| Row.new(self, row) }
     end
 
-    # The totals, if there were any.
+    # The totals in the report, if there were any.
     def totals
       Array.new(dimensions.size) + report["data"]["totals"][0]["values"]
     end
@@ -49,9 +73,5 @@ module GAAPI
     def totals?
       report["data"]["totals"]
     end
-
-    private
-
-    attr_reader :response
   end
 end

data/lib/gaapi/response.rb

@@ -57,7 +57,7 @@ module GAAPI
     def reports
       @reports ||= if success?
                      to_json["reports"].map do |report|
-                       Report.new(self, report)
+                       Report.new(report)
                      end
                    else
                      []

data/lib/gaapi/row.rb

@@ -1,7 +1,17 @@
 # frozen_string_literal: true
 
 module GAAPI
-  # A single row from a query to Google Analytics
+  # A single row from a report from a query to Google Analytics.
+  #
+  # In addition to the methods listed, `Row` provides methods to access the
+  # value of a dimension or metric by the name of the dimension or metric.
+  # @!macro [new] method_missing
+  #   The name is the snake case version of the Google Analytics dimension or
+  #   metric name, minus the `ga:` prefix. For example, you can access the metric
+  #   `ga:sessionDuration` by writing `row.session_duration`.
+  #
+  #   In the case of the metrics, the value returned is the appropriate Ruby type
+  #   for the metric. For example, an INTEGER metric is returned as a Ruby integer.
   class Row
     # An array of the dimension values, in the order that they appear in the
     # dimension headers.
@@ -14,7 +24,16 @@ module GAAPI
       @row = row
     end
 
-    # Define and call methods for the columns in the report.
+    # Return if the data is golden, meaning it won't change if the query is re-run
+    # at a later time. The is a lag between the end of a date period and when
+    # Google Analytics has completely consolidated all the tracking data.
+    def is_data_golden
+      report.is_data_golden
+    end
+
+    # Define and call methods to return the value of the dimensions and metrics
+    # in the report.
+    # @!macro method_missing
     def method_missing(method, *args)
       if (i = dimension_method_names.find_index(method))
         define_singleton_method(method) do
@@ -32,21 +51,30 @@ module GAAPI
     end
 
     # An array of the metric values, in the order that they appear in the
-    # metric headers.
+    # metric headers. These are the raw values as returned by the Google Analytics
+    # query, in other words, they're strings.
     def metrics
-      # NOTE: There is one entry in the `row["metrics"]` array for each data range.
+      # NOTE: There is one entry in the `row["metrics"]` array for each date range.
       # Since currently we only support one date range, this following index is
       # always 0.
       row["metrics"][0]["values"]
     end
 
+    # Return the nextPageToken, if any, indicating that the query exceeded
+    # the maximum number of rows allowed in a single response, and that the client
+    # has to ask for the rest of the data.
+    def next_page_token
+      # puts "Next Page Token report: #{report.report}"
+      report.next_page_token
+    end
+
     def respond_to_missing?
       true
     end
 
     # Return the data from the row as an Array, ordered by:
-    #   Headers first, in the order that they appear in the Report#headers array.
-    #   Metrics next, in the order that they appear in the Rport#metrics array.
+    # - Headers first, in the order that they appear in the Report#headers array.
+    # - Metrics next, in the order that they appear in the Report#metrics array.
     def to_a
       dimensions + metrics
     end

data/lib/gaapi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GAAPI
-  VERSION = "0.4.3"
+  VERSION = "0.5.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: gaapi
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - Larry Reid
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-11-28 00:00:00.000000000 Z
+date: 2018-12-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chandler