keen 0.8.6 → 0.8.7

data/README.md

@@ -153,6 +153,12 @@ Keen.query("median", "purchases", :target_property => "price")  # => 60
 
 This simplifes querying code where the analysis type is dynamic.
 
+##### Query Options
+
+Each query method or alias takes an optional hash of options as an additional parameter. Possible keys are:
+
+`:response` – Set to `:all_keys` to return the full API response (usually only the value of the `"result"` key is returned).
+
 ##### Getting Query URLs
 
 Sometimes you just want the URL for a query, but don't actually need to run it. Maybe to paste into a dashboard, or open in your browser. In that case, use the `query_url` method:
@@ -200,6 +206,20 @@ Keen.delete(:signups, filters: [{
 
 ### Other code examples
 
+#### Overwriting event timestamps
+
+Two time-related properties are included in your event automatically. The properties “keen.timestamp” and “keen.created_at” are set at the time your event is recorded. You have the ability to overwrite the keen.timestamp property. This could be useful, for example, if you are backfilling historical data. Be sure to use [ISO-8601 Format](https://keen.io/docs/event-data-modeling/event-data-intro/#iso-8601-format).
+
+Keen stores all date and time information in UTC!
+
+```ruby
+Keen.publish(:sign_ups, {
+  :keen => { :timestamp => "2012-12-14T20:24:01.123000+00:00" },
+  :username => "lloyd",
+  :referred_by => "harry" 
+})
+```
+
 #### Batch publishing
 
 The keen-gem supports publishing events in batches via the `publish_batch` method. Here's an example usage:
@@ -323,6 +343,9 @@ EventMachine itself won't do this because it runs in a different thread. Here's
 
 ### Changelog
 
+##### 0.8.7
++ Add support for returning all keys back from query API responses
+
 ##### 0.8.6
 + Add support for getting [query URLs](https://github.com/keenlabs/keen-gem/pull/47)
 + Make the `query` method public so code supporting dynamic analysis types is easier to write

data/lib/keen/client.rb

@@ -80,15 +80,15 @@ module Keen
     end
 
     def ensure_write_key!
-      raise ConfigurationError, "Write Key must be set for sending events" unless self.write_key
+      raise ConfigurationError, "Write Key must be set for this operation" unless self.write_key
     end
 
     def ensure_master_key!
-      raise ConfigurationError, "Master Key must be set for delete event collections" unless self.master_key
+      raise ConfigurationError, "Master Key must be set for this operation" unless self.master_key
     end
 
     def ensure_read_key!
-      raise ConfigurationError, "Read Key must be set for queries" unless self.read_key
+      raise ConfigurationError, "Read Key must be set for this operation" unless self.read_key
     end
 
     def api_event_collection_resource_path(event_collection)
@@ -104,13 +104,7 @@ module Keen
       preprocess_percentile(params)
       preprocess_property_names(params)
 
-      query_params = ""
-      params.each do |param, value|
-        query_params << "#{param}=#{CGI.escape(value)}&"
-      end
-
-      query_params.chop!
-      query_params
+      params.map { |key, value| "#{key}=#{CGI.escape(value)}" }.join('&')
     end
 
     def preprocess_encodables(params)

data/lib/keen/client/querying_methods.rb

@@ -15,8 +15,8 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def count(event_collection, params={})
-        query(__method__, event_collection, params)
+      def count(event_collection, params={}, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a count unique query.
@@ -31,8 +31,8 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def count_unique(event_collection, params)
-        query(__method__, event_collection, params)
+      def count_unique(event_collection, params, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a minimum query.
@@ -47,8 +47,8 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def minimum(event_collection, params)
-        query(__method__, event_collection, params)
+      def minimum(event_collection, params, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a maximum query.
@@ -63,8 +63,8 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def maximum(event_collection, params)
-        query(__method__, event_collection, params)
+      def maximum(event_collection, params, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a sum query.
@@ -79,8 +79,8 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def sum(event_collection, params)
-        query(__method__, event_collection, params)
+      def sum(event_collection, params, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a average query.
@@ -95,8 +95,8 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def average(event_collection, params)
-        query(__method__, event_collection, params)
+      def average(event_collection, params, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a median query.
@@ -111,8 +111,8 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def median(event_collection, params)
-        query(__method__, event_collection, params)
+      def median(event_collection, params, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a percentile query.
@@ -128,8 +128,8 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def percentile(event_collection, params)
-        query(__method__, event_collection, params)
+      def percentile(event_collection, params, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a select_unique query.
@@ -144,8 +144,8 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def select_unique(event_collection, params)
-        query(__method__, event_collection, params)
+      def select_unique(event_collection, params, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a extraction query.
@@ -161,8 +161,8 @@ module Keen
       #   filters (optional) [Array]
       #   timezone (optional)
       #   latest (optional)
-      def extraction(event_collection, params={})
-        query(__method__, event_collection, params)
+      def extraction(event_collection, params={}, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Runs a funnel query.
@@ -172,8 +172,8 @@ module Keen
       # @param event_collection
       # @param params [Hash] (optional)
       #   steps (required)
-      def funnel(params)
-        query(__method__, nil, params)
+      def funnel(params, options={})
+        query(__method__, nil, params, options)
       end
 
       # Runs a multi-analysis query
@@ -189,8 +189,8 @@ module Keen
       #     label (required)
       #     analysis_type (required)
       #     target_property (optional)
-      def multi_analysis(event_collection, params)
-        query(__method__, event_collection, params)
+      def multi_analysis(event_collection, params, options={})
+        query(__method__, event_collection, params, options)
       end
 
       # Returns the URL for a Query without running it
@@ -205,7 +205,7 @@ module Keen
       # @param options
       #   exclude_api_key
       def query_url(analysis_type, event_collection, params={}, options={})
-        str = _query_url(analysis_type, event_collection, params)
+        str = _query_url(analysis_type, event_collection, params, options)
         str << "&api_key=#{self.read_key}" unless options[:exclude_api_key]
         str
       end
@@ -219,16 +219,18 @@ module Keen
       #   interval (optional)
       #   filters (optional) [Array]
       #   timezone (optional)
-      def query(analysis_type, event_collection, params={})
-        url = _query_url(analysis_type, event_collection, params)
+      def query(analysis_type, event_collection, params={}, options={})
+        url = _query_url(analysis_type, event_collection, params, options)
         response = get_response(url)
         response_body = response.body.chomp
-        process_response(response.code, response_body)["result"]
+        api_result = process_response(response.code, response_body)
+        api_result = api_result["result"] unless options[:response] == :all_keys
+        api_result
       end
 
       private
 
-      def _query_url(analysis_type, event_collection, params={})
+      def _query_url(analysis_type, event_collection, params={}, options={})
         ensure_project_id!
         ensure_read_key!
 

data/lib/keen/version.rb

@@ -1,3 +1,3 @@
 module Keen
-  VERSION = "0.8.6"
+  VERSION = "0.8.7"
 end

data/spec/integration/api_spec.rb

@@ -238,6 +238,18 @@ describe "Keen IO API" do
       results.should == [2, 1]
     end
 
+    it "should return all keys of valid funnel if full result option is passed" do
+      steps = [{
+        :event_collection => event_collection,
+        :actor_property => "username"
+      }, {
+        :event_collection => @returns_event_collection,
+        :actor_property => "username"
+      }]
+      results = Keen.funnel({ :steps => steps }, { :response => :all_keys })
+      results["result"].should == [2, 1]
+    end
+
     it "should apply filters" do
       Keen.count(event_collection, :filters => [{
         :property_name => "username",

data/spec/keen/client/publishing_methods_spec.rb

@@ -69,7 +69,7 @@ describe Keen::Client::PublishingMethods do
         Keen::Client.new(
           :project_id => "12345"
         ).publish(collection, event_properties)
-      }.to raise_error(Keen::ConfigurationError, "Keen IO Exception: Write Key must be set for sending events")
+      }.to raise_error(Keen::ConfigurationError, "Keen IO Exception: Write Key must be set for this operation")
     end
   end
 
@@ -100,7 +100,7 @@ describe Keen::Client::PublishingMethods do
         Keen::Client.new(
           :project_id => "12345"
         ).publish_batch(events)
-      }.to raise_error(Keen::ConfigurationError, "Keen IO Exception: Write Key must be set for sending events")
+      }.to raise_error(Keen::ConfigurationError, "Keen IO Exception: Write Key must be set for this operation")
     end
 
     it "should publish a batch of events" do
@@ -240,7 +240,7 @@ describe Keen::Client::PublishingMethods do
           Keen::Client.new(
             :project_id => "12345"
           ).publish_batch_async(events)
-        }.to raise_error(Keen::ConfigurationError, "Keen IO Exception: Write Key must be set for sending events")
+        }.to raise_error(Keen::ConfigurationError, "Keen IO Exception: Write Key must be set for this operation")
       end
 
       describe "deferrable callbacks" do

data/spec/keen/client/querying_methods_spec.rb

@@ -19,14 +19,14 @@ describe Keen::Client do
 
     ["minimum", "maximum", "sum", "average", "count", "count_unique", "select_unique", "extraction", "multi_analysis", "median", "percentile"].each do |query_name|
       it "should call keen query passing the query name" do
-        client.should_receive(:query).with(query_name.to_sym, event_collection, params)
+        client.should_receive(:query).with(query_name.to_sym, event_collection, params, {})
         client.send(query_name, event_collection, params)
       end
     end
 
     describe "funnel" do
       it "should call keen query w/o event collection" do
-        client.should_receive(:query).with(:funnel, nil, params)
+        client.should_receive(:query).with(:funnel, nil, params, {})
         client.funnel(params)
       end
     end
@@ -43,7 +43,7 @@ describe Keen::Client do
       it "should require a read key" do
         expect {
           Keen::Client.new(:project_id => project_id).count("users", {})
-        }.to raise_error(Keen::ConfigurationError, "Keen IO Exception: Read Key must be set for queries")
+        }.to raise_error(Keen::ConfigurationError, "Keen IO Exception: Read Key must be set for this operation")
       end
     end
 
@@ -140,6 +140,13 @@ describe Keen::Client do
         test_query("&timeframe=#{timeframe_str}", options = {:timeframe => timeframe})
         options.should eq({:timeframe => timeframe})
       end
+
+      it "should return the full API response if the response option is set to all_keys" do
+        expected_url = query_url("funnel", "?steps=#{MultiJson.encode([])}")
+        stub_keen_get(expected_url, 200, :result => [1])
+        api_response = query.call("funnel", nil, { :steps => [] }, { :response => :all_keys })
+        api_response.should == { "result" => [1] }
+      end
     end
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keen
 version: !ruby/object:Gem::Version
-  version: 0.8.6
+  version: 0.8.7
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-08-04 00:00:00.000000000 Z
+date: 2014-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json