keen 0.7.3 → 0.7.4

data/.travis.yml

@@ -10,7 +10,7 @@ rvm:
 
 env:
   - PATTERN=keen
-  - PATTERN=integration KEEN_WRITE_KEY=f806128f31c349fda124b62d1f4cf4b2 KEEN_READ_KEY=f806128f31c349fda124b62d1f4cf4b2 KEEN_PROJECT_ID=50e5ffa6897a2c319b000000
+  - PATTERN=integration KEEN_MASTER_KEY=f806128f31c349fda124b62d1f4cf4b2 KEEN_WRITE_KEY=f806128f31c349fda124b62d1f4cf4b2 KEEN_READ_KEY=f806128f31c349fda124b62d1f4cf4b2 KEEN_PROJECT_ID=50e5ffa6897a2c319b000000
   - PATTERN=synchrony
 
 matrix:

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    keen (0.7.3)
+    keen (0.7.4)
       multi_json (~> 1.0)
 
 GEM
@@ -51,7 +51,7 @@ GEM
       rb-kqueue (>= 0.2)
     lumberjack (1.0.3)
     method_source (0.8.1)
-    multi_json (1.7.3)
+    multi_json (1.7.4)
     pry (0.9.12.1)
       coderay (~> 1.0.5)
       method_source (~> 0.8)

data/README.md

@@ -23,14 +23,22 @@ keen is tested with Ruby 1.8 and 1.9 on:
 
 ### Usage
 
-Before making any API calls, you must supply keen-gem with a Project ID and one or both of your Write and Read Keys.
-(If you need a Keen IO account, [sign up here](https://keen.io/) - it's free.) The Write key is required for publishing
-events, and the Read key is required for running queries.
+Before making any API calls, you must supply keen-gem with a Project ID and one or more authentication keys.
+(If you need a Keen IO account, [sign up here](https://keen.io/signup) - it's free.) 
 
-The recommended way to do this is to set `KEEN_PROJECT_ID`, `KEEN_WRITE_KEY`, and `KEEN_READ_KEY` in your
-environment. If you're using [foreman](http://ddollar.github.com/foreman/), add this to your `.env` file:
+Setting a write key is required for publishing events. Setting a read key is required for running queries. 
+Setting a master key is required for performing deletes. You can find keys for all of your projects
+on [keen.io](https://keen.io).
 
-    KEEN_PROJECT_ID=xxxxxxxxxxxxxxxx KEEN_WRITE_KEY=yyyyyyyyyyyyy KEEN_READ_KEY=zzzzzzzzzzzzz
+The recommended way to set keys is via the environment. The keys you can set are 
+`KEEN_PROJECT_ID`, `KEEN_WRITE_KEY`, `KEEN_READ_KEY`, and `KEEN_MASTER_KEY`.
+You only need to specify the keys that correspond to the API calls you'll be performing. 
+If you're using [foreman](http://ddollar.github.com/foreman/), add this to your `.env` file:
+
+    KEEN_PROJECT_ID=aaaaaaaaaaaaaaa
+    KEEN_MASTER_KEY=xxxxxxxxxxxxxxx
+    KEEN_WRITE_KEY=yyyyyyyyyyyyyyy
+    KEEN_READ_KEY=zzzzzzzzzzzzzzz
 
 If not, make to to export the variable into your shell or put it before the command you use to start your server.
 
@@ -38,23 +46,25 @@ When you deploy, make sure your production environment variables are set. For ex
 set [config vars](https://devcenter.heroku.com/articles/config-vars) on Heroku. (We recommend this
 environment-based approach because it keeps sensitive information out of the codebase. If you can't do this, see the alternatives below.)
 
-If your environment is set up property, `Keen` is ready to go immediately. Publish an event like this:
+Once your environment is properly configured, the `Keen` object is ready to go immediately.
+
+### Publishing events
+
+Publishing events requires that `KEEN_WRITE_KEY` is set. Publish an event like this:
 
 ```ruby
-Keen.publish("sign_ups", { :username => "lloyd", :referred_by => "harry" })
+Keen.publish(:sign_ups, { :username => "lloyd", :referred_by => "harry" })
 ```
 
-This will publish an event to the 'sign_ups' collection with the `username` and `referred_by` properties set.
-
-The event properties are arbitrary JSON, and the event collection need not exist in advance.
-If it doesn't exist, Keen IO will create it on the first request.
+This will publish an event to the `sign_ups` collection with the `username` and `referred_by` properties set. 
+The event properties can be any valid Ruby hash and nested properties are allowed. You can learn more about data modeling with Keen IO with the [Data Modeling Guide](https://keen.io/docs/event-data-modeling/event-data-intro/).
 
-You can learn more about data modeling with Keen IO with the [Data Modeling Guide](https://keen.io/docs/event-data-modeling/event-data-intro/).
+The event collection need not exist in advance. If it doesn't exist, Keen IO will create it on the first request.
 
 ### Asynchronous publishing
 
-Publishing events shouldn't slow your application down. It shouldn't make your
-users wait longer for their request to finish.
+Publishing events shouldn't slow your application down or make
+users wait longer for page loads & server requests.
 
 The Keen IO API is fast, but any synchronous network call you make will
 negatively impact response times. For this reason, we recommend you use the `publish_async`
@@ -77,7 +87,7 @@ Thread.new { EventMachine.run }
 ```
 
 The best place for this is in an initializer, or anywhere that runs when your app boots up.
-Here's a good blog article that explains more about this approach - [EventMachine and Passenger](http://railstips.org/blog/archives/2011/05/04/eventmachine-and-passenger/).
+Here's a useful blog article that explains more about this approach - [EventMachine and Passenger](http://railstips.org/blog/archives/2011/05/04/eventmachine-and-passenger/).
 
 And here's a gist that shows an example of [Eventmachine with Unicorn](https://gist.github.com/jonkgrimes/5103321). Thanks to [jonkgrimes](https://github.com/jonkgrimes) for sharing this with us!
 
@@ -96,11 +106,9 @@ to resume processing immediately.
 
 The Keen IO API provides rich querying capabilities against your event data set. For more information, see the [Data Analysis API Guide](https://keen.io/docs/data-analysis/).
 
-Queries require that a Read Key is provided. Just like project ID, we encourage that you set this as an environment variable:
+Running queries requires that `KEEN_READ_KEY` is set.
 
-    KEEN_READ_KEY=yyyyyyyyyyyyyyyy
-
-Here's are some examples of querying with keen-gem. Let's assume you've added some events to the "purchases" collection.
+Here are some examples of querying with keen-gem. Let's assume you've added some events to the "purchases" collection.
 
 ```ruby
 Keen.count("purchases") # => 100
@@ -112,7 +120,7 @@ Keen.average("purchases", :target_property => "price")  # => 60
 Keen.sum("purchases", :target_property => "price", :group_by => "item.id")  # => [{ "item.id": 123, "result": 240 }, { ... }]
 
 Keen.count_unique("purchases", :target_property => "username")  # => 3
-Keen.select_unique("purchases", :target_property => "username")  # => ["bob", "linda", "travis"]
+Keen.select_unique("purchases", :target_property => "username")  # => ["Bob", "Linda", "Travis"]
 
 Keen.extraction("purchases")  # => [{ "price" => 20, ... }, { ... }]
 
@@ -127,10 +135,29 @@ Keen.multi_analysis("purchases", analyses: {
   :timeframe => 'today', :group_by => "item.id") # => [{"item.id"=>2, "gross"=>314.49, "customers"=> 8}, { ... }]
 ```
 
-Many of there queries can be performed with group by, filters, series and intervals. The API response for these is converted directly into Ruby Hash or Array.
+Many of there queries can be performed with group by, filters, series and intervals. The response is returned as a Ruby Hash or Array.
 
 Detailed information on available parameters for each API resource can be found on the [API Technical Reference](https://keen.io/docs/api/reference/).
 
+### Deleting events
+
+The Keen IO API allows you to [delete events](https://keen.io/docs/maintenance/#deleting-event-collections)
+from event collections, optionally supplying a filter to narrow the scope of what you would like to delete.
+
+Deleting events requires that the `KEEN_MASTER_KEY` is set.
+
+```ruby
+# Assume some events in the 'signups' collection
+
+# We can delete them all
+Keen.delete(:signups)  # => true
+
+# Or just delete an event corresponding to a particular user
+Keen.delete(:signups, filters: [{
+  property_name: 'username', operator: 'eq', property_value: "Bob"
+}])  # => true
+```
+
 ### Other code examples
 
 #### Batch publishing
@@ -153,7 +180,7 @@ Keen.publish_batch(
 This call would publish 2 `signups` events and 2 `purchases` events - all in just one API call.
 Batch publishing is ideal for loading historical events into Keen IO.
 
-#### Authentication
+#### Configurable and per-client authentication
 
 To configure keen-gem in code, do as follows:
 
@@ -161,14 +188,16 @@ To configure keen-gem in code, do as follows:
 Keen.project_id = 'xxxxxxxxxxxxxxx'
 Keen.write_key = 'yyyyyyyyyyyyyyy'
 Keen.read_key = 'zzzzzzzzzzzzzzz'
+Keen.master_key = 'aaaaaaaaaaaaaaa'
 ```
 
-You can also configure individual client instances as follows:
+You can also configure unique client instances as follows:
 
 ```ruby
 keen = Keen::Client.new(:project_id => 'xxxxxxxxxxxxxxx',
                         :write_key  => 'yyyyyyyyyyyyyyy',
-                        :read_key   => 'zzzzzzzzzzzzzzz')
+                        :read_key   => 'zzzzzzzzzzzzzzz',
+                        :master_key => 'aaaaaaaaaaaaaaa')
 ```
 
 #### em-synchrony
@@ -197,6 +226,10 @@ To track email opens, simply add an image to your email template that points to
 
 ### Changelog
 
+##### 0.7.4
++ Add support for deletes (thanks again [cbartlett](https://github.com/cbartlett)!)
++ Allow event collection names for publishing/deleting methods to be symbols
+
 ##### 0.7.3
 + Add batch publishing support
 + Allow event collection names for querying methods to be symbols. Thanks to [cbartlett](https://github.com/cbartlett).

data/lib/keen.rb

@@ -40,6 +40,9 @@ module Keen
                    :sum, :average, :select_unique, :funnel, :extraction,
                    :multi_analysis
 
+    def_delegators :default_client,
+                   :delete
+
     attr_writer :logger
 
     def logger
@@ -57,6 +60,7 @@ module Keen
         :project_id => ENV['KEEN_PROJECT_ID'],
         :write_key => ENV['KEEN_WRITE_KEY'],
         :read_key => ENV['KEEN_READ_KEY'],
+        :master_key => ENV['KEEN_MASTER_KEY'],
         :api_url => ENV['KEEN_API_URL']
       )
     end

data/lib/keen/client.rb

@@ -2,6 +2,7 @@ require 'keen/http'
 require 'keen/version'
 require 'keen/client/publishing_methods'
 require 'keen/client/querying_methods'
+require 'keen/client/maintenance_methods'
 
 require 'openssl'
 require 'multi_json'
@@ -11,8 +12,9 @@ module Keen
   class Client
     include Keen::Client::PublishingMethods
     include Keen::Client::QueryingMethods
+    include Keen::Client::MaintenanceMethods
 
-    attr_accessor :project_id, :write_key, :read_key, :api_url
+    attr_accessor :project_id, :write_key, :read_key, :master_key, :api_url
 
     CONFIG = {
       :api_url => "https://api.keen.io",
@@ -40,8 +42,8 @@ module Keen
         }.merge(args[3] || {})
       end
 
-      self.project_id, self.write_key, self.read_key = options.values_at(
-        :project_id, :write_key, :read_key)
+      self.project_id, self.write_key, self.read_key, self.master_key = options.values_at(
+        :project_id, :write_key, :read_key, :master_key)
 
       self.api_url = options[:api_url] || CONFIG[:api_url]
     end
@@ -57,6 +59,8 @@ module Keen
           Keen.logger.warn("Invalid JSON for response code #{status_code}: #{response_body}")
           return {}
         end
+      when 204
+        return true
       when 400
         raise BadRequestError.new(response_body)
       when 401
@@ -76,10 +80,44 @@ module Keen
       raise ConfigurationError, "Write Key must be set for sending events" unless self.write_key
     end
 
+    def ensure_master_key!
+      raise ConfigurationError, "Master Key must be set for delete event collections" unless self.master_key
+    end
+
     def ensure_read_key!
       raise ConfigurationError, "Read Key must be set for queries" unless self.read_key
     end
 
+    def api_event_collection_resource_path(event_collection)
+      "/#{api_version}/projects/#{project_id}/events/#{URI.escape(event_collection.to_s)}"
+    end
+
+    def preprocess_params(params)
+      if params.key?(:filters)
+        params[:filters] = MultiJson.encode(params[:filters])
+      end
+
+      if params.key?(:steps)
+        params[:steps] = MultiJson.encode(params[:steps])
+      end
+
+      if params.key?(:analyses)
+        params[:analyses] = MultiJson.encode(params[:analyses])
+      end
+
+      if params.key?(:timeframe) && params[:timeframe].is_a?(Hash)
+        params[:timeframe] = MultiJson.encode(params[:timeframe])
+      end
+
+      query_params = ""
+      params.each do |param, value|
+        query_params << "#{param}=#{URI.escape(value)}&"
+      end
+
+      query_params.chop!
+      query_params
+    end
+
     def method_missing(_method, *args, &block)
       if config = CONFIG[_method.to_sym]
         if config.is_a?(Proc)

data/lib/keen/client/maintenance_methods.rb

@@ -0,0 +1,31 @@
+module Keen
+  class Client
+    module MaintenanceMethods
+
+      # Runs a delete query.
+      # See detailed documentation here:
+      # https://keen.io/docs/maintenance/#deleting-event-collections
+      #
+      # @param event_collection
+      # @param params [Hash] (optional)
+      #   filters (optional) [Array]
+      def delete(event_collection, params={})
+        ensure_project_id!
+        ensure_master_key!
+
+        query_params = preprocess_params(params) if params != {}
+
+        begin
+          response = Keen::HTTP::Sync.new(self.api_url).delete(
+              :path => [api_event_collection_resource_path(event_collection), query_params].compact.join('?'),
+              :headers => api_headers(self.master_key, "sync"))
+        rescue Exception => http_error
+          raise HttpError.new("Couldn't perform delete of #{event_collection} on Keen IO: #{http_error.message}", http_error)
+        end
+
+        response_body = response.body ? response.body.chomp : ''
+        process_response(response.code, response_body)
+      end
+    end
+  end
+end

data/lib/keen/client/publishing_methods.rb

@@ -126,10 +126,6 @@ module Keen
         process_response(response.code, response.body.chomp)
       end
 
-      def api_event_collection_resource_path(event_collection)
-        "/#{api_version}/projects/#{project_id}/events/#{URI.escape(event_collection)}"
-      end
-
       def api_events_resource_path
         "/#{api_version}/projects/#{project_id}/events"
       end

data/lib/keen/client/querying_methods.rb

@@ -182,32 +182,6 @@ module Keen
         process_response(response.code, response_body)["result"]
       end
 
-      def preprocess_params(params)
-        if params.key?(:filters)
-          params[:filters] = MultiJson.encode(params[:filters])
-        end
-
-        if params.key?(:steps)
-          params[:steps] = MultiJson.encode(params[:steps])
-        end
-
-        if params.key?(:analyses)
-          params[:analyses] = MultiJson.encode(params[:analyses])
-        end
-
-        if params.key?(:timeframe) && params[:timeframe].is_a?(Hash)
-          params[:timeframe] = MultiJson.encode(params[:timeframe])
-        end
-
-        query_params = ""
-        params.each do |param, value|
-          query_params << "#{param}=#{URI.escape(value)}&"
-        end
-
-        query_params.chop!
-        query_params
-      end
-
       def api_query_resource_path(analysis_type)
         "/#{self.api_version}/projects/#{self.project_id}/queries/#{analysis_type}"
       end

data/lib/keen/http.rb

@@ -28,6 +28,12 @@ module Keen
           :path, :headers)
         @http.get(path, headers)
       end
+
+      def delete(options)
+        path, headers = options.values_at(
+          :path, :headers)
+        @http.delete(path, headers)
+      end
     end
 
     class Async

data/lib/keen/version.rb

@@ -1,3 +1,3 @@
 module Keen
-  VERSION = "0.7.3"
+  VERSION = "0.7.4"
 end

data/spec/integration/api_spec.rb

@@ -164,4 +164,25 @@ describe "Keen IO API" do
       }]).should == 1
     end
   end
+
+  describe "deletes" do
+    let(:event_collection) { "delete_test_#{rand(10000)}" }
+
+    before do
+      Keen.publish(event_collection, :delete => "me")
+      Keen.publish(event_collection, :delete => "you")
+      sleep(3)
+    end
+
+    it "should delete the event" do
+      Keen.count(event_collection).should == 2
+      Keen.delete(event_collection, :filters => [
+        { :property_name => "delete", :operator => "eq", :property_value => "me" }
+      ])
+      sleep(3)
+      results = Keen.extraction(event_collection)
+      results.length.should == 1
+      results.first["delete"].should == "you"
+    end
+  end
 end

data/spec/keen/client/maintenance_methods_spec.rb

@@ -0,0 +1,38 @@
+require File.expand_path("../../spec_helper", __FILE__)
+
+describe Keen::Client do
+  let(:project_id) { "12345" }
+  let(:master_key) { 'pastor_of_muppets' }
+  let(:api_url) { "https://notreal.keen.io" }
+  let(:api_version) { "3.0" }
+  let(:client) { Keen::Client.new(
+    :project_id => project_id, :master_key => master_key,
+    :api_url => api_url ) }
+
+  def delete_url(event_collection, filter_params=nil)
+    "#{api_url}/#{api_version}/projects/#{project_id}/events/#{event_collection}#{filter_params ? "?filters=#{URI.escape(MultiJson.encode(filter_params[:filters]))}" : ""}"
+  end
+
+  describe '#delete' do
+    let(:event_collection) { :foodstuffs }
+
+    it 'should not require filters' do
+      url = delete_url(event_collection)
+      stub_keen_delete(url, 204)
+      client.delete(event_collection).should be_true
+      expect_keen_delete(url, "sync", master_key)
+    end
+
+    it "should accept and use filters" do
+      filters = {
+        :filters => [
+          { :property_name => "delete", :operator => "eq", :property_value => "me" }
+        ]
+      }
+      url = delete_url(event_collection, filters)
+      stub_keen_delete(url, 204).should be_true
+      client.delete(event_collection, filters)
+      expect_keen_delete(url, "sync", master_key)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -23,6 +23,10 @@ module Keen::SpecHelpers
     stub_keen_request(:get, url, status, MultiJson.encode(response_body))
   end
 
+  def stub_keen_delete(url, status)
+    stub_keen_request(:delete, url, status, "")
+  end
+
   def expect_keen_request(method, url, body, sync_or_async_ua, read_or_write_key)
     user_agent = "keen-gem, v#{Keen::VERSION}, #{sync_or_async_ua}"
     user_agent += ", #{RUBY_VERSION}, #{RUBY_PLATFORM}, #{RUBY_PATCHLEVEL}"
@@ -48,6 +52,10 @@ module Keen::SpecHelpers
     expect_keen_request(:post, url, MultiJson.encode(event_properties), sync_or_async_ua, write_key)
   end
 
+  def expect_keen_delete(url, sync_or_async_ua, master_key)
+    expect_keen_request(:delete, url, "", sync_or_async_ua, master_key)
+  end
+
   def api_event_collection_resource_url(base_url, collection)
     "#{base_url}/3.0/projects/#{project_id}/events/#{collection}"
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keen
 version: !ruby/object:Gem::Version
-  version: 0.7.3
+  version: 0.7.4
   prerelease: 
 platform: ruby
 authors:
@@ -11,7 +11,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-17 00:00:00.000000000 Z
+date: 2013-05-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multi_json
@@ -48,12 +48,14 @@ files:
 - keen.gemspec
 - lib/keen.rb
 - lib/keen/client.rb
+- lib/keen/client/maintenance_methods.rb
 - lib/keen/client/publishing_methods.rb
 - lib/keen/client/querying_methods.rb
 - lib/keen/http.rb
 - lib/keen/version.rb
 - spec/integration/api_spec.rb
 - spec/integration/spec_helper.rb
+- spec/keen/client/maintenance_methods_spec.rb
 - spec/keen/client/publishing_methods_spec.rb
 - spec/keen/client/querying_methods_spec.rb
 - spec/keen/client_spec.rb
@@ -89,6 +91,7 @@ summary: Keen IO API Client
 test_files:
 - spec/integration/api_spec.rb
 - spec/integration/spec_helper.rb
+- spec/keen/client/maintenance_methods_spec.rb
 - spec/keen/client/publishing_methods_spec.rb
 - spec/keen/client/querying_methods_spec.rb
 - spec/keen/client_spec.rb