qualaroo 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0786649bc54770340d593a21dba5213b8dbef351
-  data.tar.gz: 6063f24b5f99f7e26f015b2bbdfa84827582b137
+  metadata.gz: fec45505202df68cc727759c7a89a3493c0fd417
+  data.tar.gz: ef911e68228d71799f82278bed36127d50f0b964
 SHA512:
-  metadata.gz: 6de4cb9df94fb34ee2b8aecc930672b37c0988631778697f64229a61bee404c86303b6f73c59d7accb1b0f0e0e4dc8cb67830f913d8944172b1090fc1111d355
-  data.tar.gz: 0224559f4ffc0e52827416194acc90fed7f2480b4bf950e9e6dd2d71fe32ab08eae7a7c8f85295923c372a235fac666c43f6fe9d82ce2c50a014b32ab27c4fef
+  metadata.gz: caaea8eda77c32f9b2266a4d5f33c89c03f2669b4229b115185a712e203cfb15765072652dadb2bb49cdf957e5b349c41449447aee35f123c80041ac26e9dbaa
+  data.tar.gz: eff1587501f87266ad0d36ca96a37ec73ca9ceda874bf7d5ef5c9837a12babd0c13164689362773de8f18ba18378d10f2a98075a9e7c13f496164a6ea0b936a8

data/README.md

@@ -1,6 +1,7 @@
 # Qualaroo
 
-TODO: Write a gem description
+A ruby library to connect to Qualaroo's API. For more information on
+their API, check out the documentation here: http://help.qualaroo.com/hc/en-us/sections/200469946-API-Documentation
 
 ## Installation
 
@@ -20,7 +21,85 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+First, you'll need your API key which you can find here: https://app.qualaroo.com/account
+
+### Set up your API keys
+
+You can create an instance of the API client:
+
+    qualaroo = Qualaroo::Client.new("your_api_key", "your_api_secret")
+
+Alternatively, you can set this globally and use this in an initializer
+in Rails like `config/initializers/qualaroo.rb`:
+
+    Qualaroo::Client.api_key    = "your_api_key"
+    Qualaroo::Client.api_secret = "your_api_secret"
+
+You can also set the environment variables `QUALAROO_API_KEY` and
+`QUALAROO_API_SECRET` in your `application.yml` and Qualaroo will
+automatically detect this. That means, you can set up API access by just
+specifying:
+
+    qualaroo = Qualaroo::Client.new
+
+### Responses
+
+Once you've set your API keys, you can access responses to nudges:
+
+    qualaroo = Qualaroo::Client.new
+    qualaroo.responses("your_nudge_id")
+
+    # or if you set the keys globally
+
+    Qualaroo::Client.responses("your_nudge_id")
+
+This returns the first 500 responses as a Ruby hash.
+
+Their API also accepts various options:
+
+    # Date Ranges
+    You can request records for a particular date range. To do this, add start_date and/or end_date parameters to the URL. The value of these parameters must be a integer representing "UNIX time" in seconds. For example, the date/time "2013-07-15 17:47:24 -0700" must be represented as 1373935644.
+
+    # Pagination
+    offset -- a non-negative integer. For example, offset=1000 means that the API will return records that match your query starting with response number 1001. If offset is not provided, the API will start from the beginning, response number 1.
+    limit -- the number of records you want to get in one response. The number must be between 0 and 500. If limit is not provided, the API will retrieve up to 500 responses.
+
+You must pass in an integer version of a time to `start_date` or
+`end_date` for it to be handled properly:
+
+    qualaroo = Qualaroo::Client.new
+    qualaroo.responses("your_nudge_id", {
+      start_date: Time.zone.yesterday.to_i,
+      end_date: Time.zone.now.to_i,
+      offset: 500,
+      limit: 30
+    })
+
+    # or if you set the keys globally
+
+    Qualaroo::Client.responses("your_nudge_id", {
+      start_date: Time.zone.yesterday.to_i,
+      end_date: Time.zone.now.to_i,
+      offset: 500,
+      limit: 30
+    })
+
+### All Responses For A Nudge
+
+If you want to access all the responses from a Nudge without dealing
+with pagination, you can use the `all_responses` method to do this. It
+will make a series of API requests and collect the results and return
+them to you all together.
+
+    qualaroo = Qualaroo::Client.new
+    qualaroo.all_responses("your_nudge_id)
+
+    # or if you set the keys globally
+
+    Qualaroo::Client.all_responses("your_nudge_id")
+
+You can also pass the `start_date` and `end_date` options into this
+method to get all responses over a given time period.
 
 ## Contributing
 

data/lib/qualaroo.rb

@@ -7,13 +7,38 @@ module Qualaroo
     base_uri 'app.qualaroo.com/api/v1'
     format :json
 
-    def initialize(key, secret)
-      @auth = {username: key, password: secret}
+    attr_accessor :api_key, :api_secret
+
+    def initialize(api_key, api_secret)
+      @auth = {
+        username: api_key || self.class.api_key || ENV['QUALAROO_API_KEY'],
+        password: api_secret || self.class.api_secret || ENV['QUALAROO_API_SECRET']
+      }
+    end
+
+    def responses(nudge_id, query={}, options={})
+      options.merge!(basic_auth: @auth, query: query)
+      self.class.get("/nudges/#{nudge_id}/responses.json", options)
+    end
+
+    def all_responses(nudge_id, query={}, options={})
+      offset = 0
+      all_responses = []
+
+      while (page_responses = responses(nudge_id, query.merge(offset: offset), options)) && page_responses.any?
+        all_responses += page_responses
+        offset += 500
+      end
+
+      all_responses
     end
 
-    def responses(survey_id, options={})
-      options.merge!(basic_auth: @auth)
-      self.class.get "/nudges/#{survey_id}/responses.json", options
+    class << self
+      attr_accessor :api_key, :api_secret
+
+      def method_missing(sym, *args, &block)
+        new(api_key, api_secret).send(sym, *args, &block)
+      end
     end
   end
 end

data/lib/qualaroo/version.rb

@@ -1,3 +1,3 @@
 module Qualaroo
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: qualaroo
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Chris Oliver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-18 00:00:00.000000000 Z
+date: 2014-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler