typeform_data 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 876713987fcf2c378c84995bf1a5c3b0d460755a
-  data.tar.gz: eaf7a7355ffda4252d318934b02aa806a215544d
+  metadata.gz: f66614378d50f785ebb54f8e8739bb30ddbc5f48
+  data.tar.gz: 91ef3fe46c067e7f11f5a503e6dc099ce1fe28d7
 SHA512:
-  metadata.gz: 3d0b3c91030dd7e26f4f9eb89ce2adf4ba02b7b6e09f885fa22ea1ad12979951cfb88e968d1272cfa9d093cfee8223151b32b8cbf9b469c1251f8435f3295afd
-  data.tar.gz: e1c74927ec69c7f570d25e5bf8e363faf4df9fde039ca91fee591d7bdebcd3d74ae33f0f6fb62336ee8245c0041e8c0300b348ce99b780392e7c5a615f4cf1ea
+  metadata.gz: 02d193b05183e53f3774df96873d6847e353b6f98e3042bd5344f9da37bf5a493e7e6a3c5eb6520646d6d54d8202aff81db045dfb91c0c065630e36c6e12f623
+  data.tar.gz: 24f0f010677b83ca46d8b547ec11f66ec6cc95229789fafc01eb142bb9dd95d21e41bfb5beb383125af74e9e63e8f07f72bebf50262b4d8a06de93252518dc36

data/README.md

@@ -1,27 +1,74 @@
 # TypeformData
 
-A Ruby client for Typeform's Data API (https://www.typeform.com/help/data-api/).
+A Ruby client for Typeform's [Data API](https://www.typeform.com/help/data-api/).
 
-This is alpha software and doesn't currently cover all the use cases you'd probably expect. I've just finished implementing response fetching (including de-pagination, so you can fetch _all_ the responses in one method call), but the full data model isn't built out yet.
+**Warning**: this is alpha software, and hasn't been thoroughly vetted in production yet. Use at your own risk :).
 
-Unless you're eager to dive into the code, I'd suggest waiting until next week to check out this gem.
+## Usage:
 
-Ruby 2.3
+```
+client = TypeformData::Client.new(api_key: 'YOUR_API_KEY')
+typeforms = client.all_typeforms
+
+typeform = typeforms.first
+=> #<TypeformData::Typeform
+ @config=#<TypeformData::Config @api_key="YOUR_API_KEY">,
+ @id="TYPEFORM_ID",
+ @name="TYPEFORM_NAME">
+```
+
+### Fetching responses
+
+```
+all_complete_responses = typeform.responses(completed: true)
+```
 
-TODO:
-  - Add more detail, and example method calls.
-  - Add an explanation: why another gem? What makes this gem different?
+Unless you specify a limit, `TypeformData::Typeform#responses` will not paginate, and will make multiple AJAX requests as needed (the Data API only returns up to 1000 responses at a time) to fetch all the matching responses.
 
-Goals:
-  - Typeform data (and invidual response data) must work with `Marshal#load` and `Marshal#dump`.
+You can also specify any of the ["Filtering Options"](https://www.typeform.com/help/data-api/) to pass along to the API call:
 
-We have to do a lot of reverse-engineering to get an API that feels reasonably intuitive.
+(*Warning*: the `token` parameter isn't working yet.)
 
-### Notes on the API
+```
+some_complete_responses = typeform.responses(limit: 500, offset: 2000, completed: true)
+two_days_of_responses = typeform.responses(from: 1470143917, since: 1470316722)
 
-  - ID vs. UID: they aren't used consistently across the docs and actual API responses.
+```
 
-## Installation
+### Questions & answers
+
+The response data you get back is represented using classes with defined relationships:
+
+```
+typeform.responses.first.answers.first.typeform == typeform
+=> true
+
+typeform.fields.map(&:text)
+=> ["What is your name?", "What are your favorite colors?", ...]
+
+typeform.responses.first.answers.map { |answer| [answer.field_text, answer.value] }`
+=> [["What is your name?", "Foo Bar"], ["What are your favorite colors?", ["blue", "orange"]]]
+
+```
+
+To access a Typeform's questions, we recommend using `TypeformData::Typeform#fields` instead of `TypeformData::Typeform#questions`. Each `TypeformData::Typeform::Answer` is associated to exactly one `TypeformData::Typeform::Field`, and one or more `TypeformData::Typeform::Question`s.
+
+## Notes on the API
+
+So far, we've found Typeform's current Data API to be confusing. In particular, there are a couple design decisions that have been a big source of confusion and friction for us:
+
+- Statements (which are sections of text in a Typeform, and can't be answered) and Hidden Fields (data passed into a form, and not provided by the user) are both included under the `'questions'` key in the API's response JSON. From the perspective of a user, we don't think of these as "questions".
+- Each option in a "Picture choice" (and, IIRC "Multiple choice" as well, if multiple choices are allowed) is returned as its own "question" in the response JSON for questions and answers. We feel that it makes more sense to model these as multiple answers to one question, i.e. an Array-valued answer.
+
+The main goal of this API wrapper is to encapsulate these implementation details (which we find confusing) and provide a more intuitive API for our application code. This means that our data model must deviating in specific places from the implicit data model expressed in the Data API's JSON responses. We're sacrificing consistency for a more intuitive client API.
+
+## Notes
+
+  - We haven't tested against any Ruby versions other than 2.3.
+  - At the moment, this gem has no runtime dependencies.
+  - Under the hood, the object relationships are implemented by storing a reference to a config object containing your API key. This is what allows you to say `answer.typeform.responses` and make an API call originating from a `TypeformData::Typeform::Answer` without having to pass in a reference to a client or your API key (again). To avoid leaking your API key, make sure to clear out the `@config` reference if you serialize any of the objects! We've already done a bit here: if you call `Marshal.dump` on a `TypeformData::ValueClass`, we only serialize attributes (not references, and not the `@config` object). 
+
+### Installation
 
 Add this line to your application's Gemfile:
 
@@ -33,25 +80,18 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
-
-    $ gem install typeform_data
-
-## Usage
-
-TODO: Write usage instructions here
-
-## Development
+### Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Releasing a new version
 
-## Contributing
+Update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/typeform_data. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+### Contributing
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/typeform_data. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
-## License
+### License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/typeform_data.rb

@@ -31,6 +31,7 @@ require 'typeform_data/client'
 require 'typeform_data/errors'
 require 'typeform_data/config'
 require 'typeform_data/value_class'
+require 'typeform_data/comparable_by_id_and_config'
 
 require 'typeform_data/requestor'
 require 'typeform_data/api_response'

data/lib/typeform_data/comparable_by_id_and_config.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+module TypeformData
+  module ComparableByIdAndConfig
+    include Comparable
+
+    # Override this method to specify a different key.
+    def sort_key
+      id
+    end
+
+    def ==(other)
+      other.sort_key == sort_key && other.config == config
+    end
+
+    def <=>(other)
+      other.sort_key <=> sort_key
+    end
+
+  end
+end

data/lib/typeform_data/typeform.rb

@@ -5,10 +5,9 @@ module TypeformData
 
   class Typeform
     include TypeformData::ValueClass
+    include TypeformData::ComparableByIdAndConfig
     readable_attributes :id, :name
 
-    # TODO: define comparison methods <=>, etc.
-
     # See https://www.typeform.com/help/data-api/ under "Filtering Options" for the full list of
     # options.
     #
@@ -23,8 +22,6 @@ module TypeformData
     # @param Hash<[String, Symbol], [String, Symbol]> params
     # @raise TypeformData::ArgumentError
     def responses(params = {})
-      # TODO: not sure what the implementation will be here, since responses_request needs to
-      # handle the awkwardness of returning multiple kinds of data at the same time.
       response = responses_request(collapse_and_validate_responses_params(params))
       set_stats(response['stats']['responses'])
 
@@ -37,28 +34,37 @@ module TypeformData
       }
     end
 
+    # Typeform's 'question' concept (as expressed in the API) has the following disadvantages:
+    #   - Each choice in a multi-select is treated as its own 'question'
+    #   - Hidden Fields are included as 'questions'
+    #   - Statements are included as 'questions'
+    #
+    # In practice, I recommend using TypeformData::Typeform#field instead, as it addresses these
+    # issues. Typeform#quesions is here so you have access to the underlying data if you need it.
+    #
+    # @return [TypeformData::Typeform::Question]
+    def questions
+      @_questions ||= fetch_questions
+    end
+
     def fields
       @_fields ||= Field.from_questions(config, questions)
     end
 
-    # In general, Typeform's "question" concept is less useful than the field concept. TODO: add
-    # more notes on this.
-    def questions
-      (@_questions ||= fetch_questions).reject(&:hidden_field?)
+    def hidden_fields
+      questions.select(&:hidden_field?)
     end
 
-    def hidden_fields
-      (@_questions ||= fetch_questions).select(&:hidden_field?)
+    def statements
+      questions.select(&:statement?)
     end
 
     def stats
       @_stats ||= fetch_stats
     end
 
-    def ==(other)
-      other.id == id && other.config == config
-    end
-
+    # This method will make an AJAX request if this Typeform's name hasn't already been set.
+    # @return [String]
     def name
       return name if name
       @name ||= client.all_typeforms.find { |typeform| typeform.id == id }.name

data/lib/typeform_data/typeform/answer.rb

@@ -5,23 +5,20 @@ module TypeformData
     class Answer
       include TypeformData::ValueClass
       include TypeformData::Typeform::ById
+      include TypeformData::ComparableByIdAndConfig
+
+      def sort_key
+        field_id
+      end
 
       # field_text may be removed in the future: we may want to normalize our data model. For
       # now, it's quite convenient to have.
-      readable_attributes :id, :value, :field_text, :response_token, :typeform_id
-
-      # IDs are of the form:
-      #
-      # - "textfield_12316024"
-      # - "listimage_12316029_choice_12322262"
       #
-      # This list may not be exhaustive-- there may be other ID formats not covererd above-- since
-      # this part of the API isn't mentioned in the documentation.
-      def question_field_id
-        id.split('_')[1]
-      end
+      # The type of 'value' is [String, Fixnum, Array<String>, Array<Fixnum>], since we are
+      # combining 'answers' from the API's JSON responses if those answers share the same field.
+      readable_attributes :field_id, :value, :field_text, :response_token, :typeform_id
 
-      def question_type
+      def field_type
         id.split('_').first
       end
 
@@ -30,6 +27,45 @@ module TypeformData
       # def response
       #   typeform.responses(token: response_token)
       # end
+
+      # In the JSON, answer 'ID's are of the form:
+      #
+      # - "textfield_12316024"
+      # - "listimage_12316029_choice_12322262"
+      #
+      # This list may not be exhaustive-- there may be other ID formats not covererd above-- since
+      # this part of the API isn't mentioned in the documentation.
+      #
+      # For our Answer object, we strip out only the 'listimage_12316029' part, giving Answers the
+      # same specificity as Fields.
+      #
+      # Use this method to create Answers when initializing a Response.
+      # @return [Array<Answer>]
+      def self.from_response_attrs(config, attrs, fields)
+        (attrs[:answers] || attrs['answers']).group_by { |id, _value|
+          field_id = id.split('_')[1]
+
+          unless field_id && field_id.length.positive?
+            raise UnexpectedError, 'Falsy field ID for answer(s)'
+          end
+
+          fields.find { |field| field.id.to_s == field_id }.tap { |matched|
+            raise UnexpectedError, 'Expected to find a matching field' unless matched
+          }
+        }.map { |field, ids_and_values|
+          values = ids_and_values.map(&:last)
+
+          Answer.new(
+            config,
+            field_id: field.id,
+            value: values.one? ? values.first : values,
+            field_text: field.text,
+            response_token: attrs[:token] || attrs['token'],
+            typeform_id: attrs[:typeform_id] || attrs['typeform_id'],
+          )
+        }
+      end
+
     end
 
   end

data/lib/typeform_data/typeform/field.rb

@@ -5,22 +5,35 @@ module TypeformData
     class Field
       include TypeformData::ValueClass
       include TypeformData::Typeform::ById
-      readable_attributes :id, :text, :typeform_id, :question_ids
+      include TypeformData::ComparableByIdAndConfig
+      readable_attributes :id, :type, :text, :typeform_id, :question_ids
 
       # The Data API includes 'statements' as part of a Typeform's "questions", despite the fact
       # that these statements don't have associated answers.
       def statement?
-        id.split('_').first == 'statement'
+        type == 'statement'
       end
 
       def self.from_questions(config, input_questions)
-        input_questions.group_by(&:field_id).map do |field_id, questions|
-          unless questions.map(&:text).uniq.length == 1
-            raise UnexpectedError, 'Expected question text to be the same based on field_id'
+        input_questions.reject(
+          &:hidden_field?
+        ).reject(
+          &:statement?
+        ).group_by(&:field_id).map do |field_id, questions|
+          unless 1 == questions.map(&:text).uniq.length && 1 == questions.map(&:type).uniq.length
+            # TODO: turn these errors into warnings.
+            raise UnexpectedError, 'Expected questions with the same field_id to have the same '\
+              'type and text'
           end
 
-          new(config, id: field_id, text: questions.first.text, question_ids: questions.map(&:id),
-                      typeform_id: questions.first.typeform_id)
+          new(
+            config,
+            id: field_id,
+            type: questions.first.type,
+            text: questions.first.text,
+            question_ids: questions.map(&:id),
+            typeform_id: questions.first.typeform_id,
+          )
         end
       end
 

data/lib/typeform_data/typeform/question.rb

@@ -5,19 +5,33 @@ module TypeformData
     class Question
       include TypeformData::ValueClass
       include TypeformData::Typeform::ById
+      include TypeformData::ComparableByIdAndConfig
+
+      # A question ID is of the form:
+      #   - opinionscale_20576123
+      #   - listimage_46576029_choice_26422755
+      #
+      # It looks like the second part of the ID is the field ID, but the Data API includes
+      # 'field_id' as a separate property in the response JSON, so I'm not sure if we can treat
+      # them as the same.
+      #
       readable_attributes :id, :question, :field_id, :typeform_id
 
       # Question#question makes for a bad API. Ideally, use Question#text instead.
       alias text question
 
+      def type
+        id.split('_').first
+      end
+
       def hidden_field?
-        id.split('_').first == 'hidden'
+        type == 'hidden'
       end
 
       # The Data API includes 'statements' as part of a Typeform's "questions", despite the fact
       # that these statements don't have associated answers.
       def statement?
-        id.split('_').first == 'statement'
+        type == 'statement'
       end
     end
 

data/lib/typeform_data/typeform/response.rb

@@ -5,8 +5,16 @@ module TypeformData
     class Response
       include TypeformData::ValueClass
       include TypeformData::Typeform::ById
+      include TypeformData::ComparableByIdAndConfig
+
       readable_attributes :token, :metadata, :hidden, :typeform_id, :answers, :completed
 
+      alias hidden_fields hidden
+
+      def sort_key
+        token
+      end
+
       # It's correct to name this attribute "completed?" and not "complete?" since it's always in
       # the past tense-- once a potential respondent leaves a Typeform unsubmitted, they can never
       # go back and complete it.
@@ -14,29 +22,14 @@ module TypeformData
         @completed == 1
       end
 
-      alias hidden_fields hidden
-
       def date_submitted
         DateTime.strptime(metadata['date_submit'], '%Y-%m-%d %H:%M:%S')
       end
 
       def initialize(config, attrs, fields)
         mapped_attrs = attrs.dup
-
-        mapped_attrs[:answers] = (attrs[:answers] || attrs['answers']).map { |id, value|
-          matching_field = fields.find { |field| field.id.to_s == id.split('_')[1] }
-          raise UnexpectedError, 'Expected to find a matching field' unless matching_field
-
-          Answer.new(
-            config,
-            id: id,
-            value: value,
-            field_text: matching_field.text,
-            response_token: attrs[:token] || attrs['token'],
-            typeform_id: attrs[:typeform_id] || attrs['typeform_id'],
-          )
-        }
-
+        mapped_attrs[:answers] = Answer.from_response_attrs(config, attrs, fields)
+        mapped_attrs.delete('answers')
         super(config, mapped_attrs)
       end
 
@@ -45,10 +38,6 @@ module TypeformData
         answers.each { |answer| answer.config = config }
       end
 
-      def ==(other)
-        other.token == token && other.config == config
-      end
-
     end
 
   end

data/lib/typeform_data/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module TypeformData
-  VERSION = '0.0.2'
+  VERSION = '0.0.3'
 end

data/typeform_data.gemspec

@@ -9,15 +9,13 @@ Gem::Specification.new do |spec|
   spec.name          = 'typeform_data'
   spec.version       = TypeformData::VERSION
   spec.authors       = ['Max Wallace']
-  spec.email         = ['maxfield.wallace@gmail.com']
+  spec.email         = ['engineering@shearwaterintl.com']
 
-  spec.summary       = 'An opinionated client for the Typeform.com Data API'
-  spec.description   = 'typeform_data is a minimal, opinionated client for the Typeform.com Data '\
-                         'API (see https://www.typeform.com/help/data-api/). The goal of this '\
-                         'project is to create a maintainable, extensible client that provides a '\
-                         "more natural object-oriented interface to Typeform.com's Data API."
+  spec.summary       = 'An opinionated, OO client for the Typeform.com Data API'
+  spec.description   = 'typeform_data is a minimal, opinionated, OO client for the Typeform.com '\
+                         'Data API with no runtime dependencies.'
 
-  spec.homepage      = 'https://github.com/shearwater-intl/typeform_data'
+  spec.homepage      = 'https://github.com/shearwaterintl/typeform_data'
   spec.license       = 'MIT'
 
   spec.files = `git ls-files -z`.split("\x0").reject { |f|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: typeform_data
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Max Wallace
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-02 00:00:00.000000000 Z
+date: 2016-08-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -136,12 +136,10 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.39'
-description: typeform_data is a minimal, opinionated client for the Typeform.com Data
-  API (see https://www.typeform.com/help/data-api/). The goal of this project is to
-  create a maintainable, extensible client that provides a more natural object-oriented
-  interface to Typeform.com's Data API.
+description: typeform_data is a minimal, opinionated, OO client for the Typeform.com
+  Data API with no runtime dependencies.
 email:
-- maxfield.wallace@gmail.com
+- engineering@shearwaterintl.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -160,6 +158,7 @@ files:
 - lib/typeform_data.rb
 - lib/typeform_data/api_response.rb
 - lib/typeform_data/client.rb
+- lib/typeform_data/comparable_by_id_and_config.rb
 - lib/typeform_data/config.rb
 - lib/typeform_data/errors.rb
 - lib/typeform_data/requestor.rb
@@ -173,7 +172,7 @@ files:
 - lib/typeform_data/value_class.rb
 - lib/typeform_data/version.rb
 - typeform_data.gemspec
-homepage: https://github.com/shearwater-intl/typeform_data
+homepage: https://github.com/shearwaterintl/typeform_data
 licenses:
 - MIT
 metadata: {}
@@ -196,5 +195,5 @@ rubyforge_project:
 rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
-summary: An opinionated client for the Typeform.com Data API
+summary: An opinionated, OO client for the Typeform.com Data API
 test_files: []