typed_form 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8fdad9dc3081cffe611c965b36e76d7e2fe8f65f
-  data.tar.gz: 42e9753fbd1c0e3e0c649f8e24666fdcfe6fe120
+  metadata.gz: d67800ceba46ef713f9fc5aa6d60390ad29d1737
+  data.tar.gz: dfe2b5bcf4c885ad9883af07d6a92f86d107572c
 SHA512:
-  metadata.gz: 3c24d68be4bbf0608ea8b937748b3345ab93880577f0f08d5d5a2ad6a09da5e080c3a83e7336afff336925921c965cad79a55facf5b6dec23e0a2240c18c7263
-  data.tar.gz: f8b605773edcbd28a69c3eff49f4a21d0c4bc23ee3d45c87c0a93cc017a53a7c8edccc4bb2de2ea67cc662e395df491aea09fce2723527570ca8e5bbfdbee254
+  metadata.gz: 3817ca0f77392d2846dca9b7f7b51fc00a5685d3caacf5a25dd90f6ec7a6a4aefa9cffa92a5d0eb8218b05099234ea14af6631512463b8edf9a8c7ee08d94b01
+  data.tar.gz: c1ed19b2752ec0e4d3fed9a2a20a913ba751c18bbf7af79ec79f359a070b4a8d6792f559f2fc65241a7cdbe3e96a7bc9a563877d1c9dad1f04fa9876d072b3af

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Change Log
 
+## [0.1.0] - 2017-03-12
+
+Adds logic for extracting data needed for Data API from incoming Webhooks. 
+
+Adds YARD documentation to gem.
+
+Separates API/Client, Data-API Form Data, and Form/Webhook responsibilities into isolated namespaces. Stabilizes Gem API around accessing form data via 
+API and loading from existing JSON data sources.
+
 ## [0.0.4] - 2017-03-10
 
 Defaults to freezing Questions after initialization, to prevent concerns with mutating data inadvertently when working with questions as value objects.

data/README.md

@@ -78,13 +78,15 @@ form_id = "typeform_form_id"
 # individual response token, provided in responses hash or via webhook data
 token = "form_token" 
 
-client = TypedForm::Client.new(api_key: api_key)
-json = client.find_form_by(form_id: form_id, token: token)
-  => # json response for that specific form submission
-
-parsed = TypedForm::JSONResponseHandler.new(json)
-form = TypedForm::FormResponse.new(parsed_questions: parsed.questions,
-                                   parsed_response: parsed.response.first)
+client = TypedForm::API::Client.new(api_key: api_key)
+form = TypedForm::Form.find_form_by(
+  client: client, 
+  form_id: form_id, 
+  token: token
+)
+
+# Or, load from existing JSON
+form = TypedForm::Form.build_form_from(json: your_json_source)
 questions = form.questions
 
 questions.first.text
@@ -103,6 +105,8 @@ questions.first.type
 
 The most common use case for this is extrapolating question and answers into a simple object that can provide a clean interface for displaying them. Question type information can be used to allow helpers to format and display different field types (most specifically dates) in a more user-friendly format.
 
+Additional documentation is available at [Rubydoc.](http://www.rubydoc.info/github/useed/typed_form)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/typed_form/api/client.rb

@@ -0,0 +1,53 @@
+module TypedForm
+  # Objects related to working with the Typeform API.
+  module API
+    # API wrapper for querying typeform's Data API.
+    # @attr [String] api_key Your Typeform API key.
+    # @see https://www.typeform.com/help/data-api/ Typeform Data API docs
+    class Client
+      attr_reader :api_key
+
+      include HTTParty
+
+      # Creates a new instance of an API client for querying the
+      # Typeform Data API.
+      # @param [String] api_key Typeform API Key
+      def initialize(api_key:)
+        @api_key = api_key
+      end
+
+      # Queries the Typeform Data API /form/ endpoint to retrieve a specific
+      # response (filtered by token) for a specific Form.
+      #
+      # @param [String] form_id Typeform Form ID
+      # @param [String] token The token for the form response you are querying
+      # @param [Hash<Object>] query_params Splats and passes along query
+      # parameters to the form's query. See
+      # https://www.typeform.com/help/data-api/ under Filtering Options for
+      # more information.
+      def find_form_by(form_id:, token:, **query_params)
+        forms_by_id(form_id: form_id, token: token, **query_params)
+      end
+
+      private
+
+      def forms_by_id(form_id:, **query_params)
+        url_params = query_params.map { |k, v| "#{k}=#{v}" }
+        request_url = [form_id, authenticated_slug(url_params)].join("?")
+        get(request_url).body
+      end
+
+      def get(slug)
+        self.class.get(base_url + slug)
+      end
+
+      def base_url
+        "https://api.typeform.com/v1/form/"
+      end
+
+      def authenticated_slug(url_params)
+        ["key=#{api_key}", url_params].join("&")
+      end
+    end
+  end
+end

data/lib/typed_form/form.rb

@@ -0,0 +1,62 @@
+module TypedForm
+  # A representation of the Typeform Form Data for a single
+  # form response.
+  #
+  # @attr_reader [String] json JSON data using Typeform's Data API schema
+  class Form
+    extend Forwardable
+    attr_accessor :json
+
+    # @!method responses
+    # @see FormData::ParsedJson#responses
+    def_delegators :parsed_json, :responses
+
+    # @!method questions
+    # @see FormSubmission#questions
+    def_delegators :submission, :questions
+
+    # Creates a new instance of a Form, to allow querying
+    def initialize(json: json)
+      @json = json
+    end
+
+    # Uses the Typeform API client to query/find the form based on the form_id
+    # and token, then builds a new Form from that JSON request.
+    # @param [API::Client] client Typeform API client instance
+    # @param [String] form_id Form ID you're querying
+    # @param [String] token The token for the response you're retrieving
+    # @return [Form] A Form, via JSON fetched from Typeform's API
+    def self.find_form_by(client:, form_id:, token:)
+      json = client.find_form_by(form_id: form_id, token: token)
+      new(json: json)
+    end
+
+    # Builds a hash of Questions matched with Answers.
+    # @return [Hash] A Hash matching { "Question" => "Answer" } format.
+    def to_hash
+      questions.each_with_object({}) { |q, hash| hash[q.text] = q.answer }
+    end
+
+    private
+
+    def submission
+      raise StandardError, "Form expects a single response" if multi_response?
+      @_submission ||= FormData::FormSubmission.new(
+        parsed_questions: parsed_json.questions,
+        parsed_response: responses.first
+      )
+    end
+
+    def multi_response?
+      responses.size > 1
+    end
+
+    def parsed_json
+      @_parsed_json ||= FormData::ParsedJson.new(json: json)
+    end
+
+    def response
+      responses.first
+    end
+  end
+end

data/lib/typed_form/form_data/answers.rb

@@ -0,0 +1,91 @@
+module TypedForm
+  # A collection of Modules that build value objects around data from the
+  # Typeform Data API.
+  module FormData
+    # A collection class which takes a collection of answers to a form, and
+    # associates the questions with answers.
+    #
+    # @attr_reader [Arendelle] parsed_response An immutable object representing
+    #   the submission data from the form.
+    # @attr_reader [Arendelle] parsed_questions An immutable object representing
+    #   the question data from the form.
+    class Answers
+      extend Forwardable
+
+      # @!method answers
+      #   @return [Arendelle] Parsed Questions from Typeform Data API JSON
+      # @!method metadata
+      #   @return [Arendelle] Parsed Metadata from Typeform Data API JSON
+      # @!method token
+      #   @return [String] Token extracted from Typeform Data API JSON
+      def_delegators :parsed_response, :answers, :metadata, :token
+
+      # @!method token
+      #   @return [String] date form was submitted, in UTC
+      def_delegators :metadata, :date_submit
+
+      attr_reader :parsed_response, :input_questions, :parsed_questions
+
+      # Builds a collection of Questions, with text extrapolated to support
+      # "piped" questions (i.e. "What is the name of your {{answer_42}}").
+      #
+      # @return [Array<Question>] Question value objects with extrapolated
+      #   text and answers.
+      def self.collate(parsed_response:, parsed_questions:, input_questions:)
+        new(parsed_response: parsed_response,
+            parsed_questions: parsed_questions,
+            input_questions: input_questions).questions
+      end
+
+      # Iterates through the existing collection of input questions to build a
+      # set of question value objects. Memoizes result.
+      # @return [Array<Question>]
+      def questions
+        @_questions ||= input_questions.map do |question|
+          Question.with_response_data(
+            question: question,
+            answer: answers_for(question.ids),
+            text: extrapolated_question_text(question)
+          )
+        end
+      end
+
+      private
+
+      private_class_method :new
+      def initialize(parsed_response:, input_questions:, parsed_questions:)
+        @parsed_response = parsed_response
+        @input_questions = input_questions
+        @parsed_questions = parsed_questions
+      end
+
+      def answers_for(ids)
+        id_answers = ids.map { |id| find_answer_by_id(id) }.compact
+        return if id_answers.size.zero?
+        id_answers.join(", ")
+      end
+
+      def extrapolated_question_text(question)
+        regex = %r(\{\{answer_(\d+)\}\})
+        id_match = question.original_text.match(regex)
+        return question.original_text unless id_match
+
+        question.original_text.gsub(regex, find_answer_by_field_id(id_match[1]))
+      end
+
+      def find_answer_by_field_id(id)
+        fields = parsed_questions.select do |question|
+          question.field_id == id.to_i
+        end
+
+        answers_found = fields.map { |f| find_answer_by_id(f.id) }.compact
+        return find_answer_by_id(fields.first.id) if answers_found.size == 1
+        raise ArgumentError, "Cannot find single answer with field ID ##{id}"
+      end
+
+      def find_answer_by_id(id)
+        answers.instance_variable_get("@#{id}")
+      end
+    end
+  end
+end

data/lib/typed_form/form_data/form_submission.rb

@@ -0,0 +1,53 @@
+module TypedForm
+  module FormData
+    # Takes an individual parsed response for a series of questions, and
+    # provides an interface for accessing the Question value objects.
+    #
+    # @attr_reader [Arendelle] parsed_questions Parsed Questions from JSON
+    # @attr_reader [Arendelle] parsed_response Parsed Answers from JSON
+    class FormSubmission
+      attr_reader :parsed_questions, :parsed_response
+
+      # Creates a new Form Submission.
+      #
+      # @param [Arendelle] parsed_questions Parsed Questions from JSON
+      # @param [Arendelle] parsed_response Parsed Answers from JSON
+      def initialize(parsed_questions:, parsed_response:)
+        @parsed_questions = parsed_questions
+        @parsed_response = parsed_response
+      end
+
+      # Builds a full set of Question value objects with answer text.
+      # @return [Array<Question>]
+      def questions
+        @_questions ||= Answers.collate(parsed_response: parsed_response,
+                                        parsed_questions: parsed_questions,
+                                        input_questions: input_questions)
+      end
+
+      private
+
+      def question_for_grouped(grouped_questions)
+        question_texts = grouped_questions.map(&:question)
+        return question_texts.first if question_texts.uniq.size == 1
+        raise ArgumentError, "Grouped questions do not have matching text"
+      end
+
+      def answerable_questions
+        parsed_questions
+          .reject { |q| q.id.match /(hidden|legal|statement|group)/ }
+          .group_by(&:field_id)
+      end
+
+      def input_questions
+        @_input_questions ||= answerable_questions.map do |field_id, grouped_q|
+          Question.new(
+            ids: grouped_q.map(&:id),
+            field_id: field_id,
+            original_text: question_for_grouped(grouped_q)
+          ).freeze
+        end
+      end
+    end
+  end
+end

data/lib/typed_form/form_data/parsed_json.rb

@@ -0,0 +1,29 @@
+module TypedForm
+  module FormData
+    # A small class which wraps functionality for parsing JSON data from the
+    # Typeform Data API.
+    # @attr_reader [String] JSON string
+    class ParsedJson
+      extend Forwardable
+      attr_reader :json
+
+      # @!method questions
+      #   @return [Arendelle] parsed_json["questions"] questions data
+      # @!method responses
+      #   @return [Arendelle] parsed_json["responses"] response data
+      def_delegators :parsed_json, :questions, :responses
+
+      # Creates and freezes JSON data.
+      # @param [String] json JSON data matching the Typeform Data API format.
+      def initialize(json:)
+        @json = json.freeze
+      end
+
+      private
+
+      def parsed_json
+        @_parsed_json ||= JSON.parse(json, object_class: Arendelle)
+      end
+    end
+  end
+end

data/lib/typed_form/form_data/question.rb

@@ -0,0 +1,62 @@
+module TypedForm
+  module FormData
+    # Question value objects represent the Typeform concept of a question, but
+    # expose an interface for querying questions and answers.
+    #
+    # @attr_reader [Array<Strong>] ids The Typeform IDs for the question. This
+    #   is ids instead of id because of the way Typeform represents multiple
+    #   choice questions.
+    # @attr_reader [Integer] field_id The Typeform Field ID for the question
+    # @attr_reader [String] The original text for the question before answers
+    #   are extrapolated back into the question.
+    # @attr [String] answer The answer of the question.
+    # @attr [Text] answer The extrapolated text for the question
+    class Question
+      attr_reader :ids, :field_id, :original_text
+      attr_accessor :answer, :text
+
+      # Creates a new Question value object, which represents any number of
+      # questions in a Typeform Form that can be logically represented as a
+      # single question. This includes both single question fields and fields
+      # like multiple choice, picture choice, etc.
+      #
+      # @param [Array<Strong>] ids The Typeform IDs for the question. This
+      #   is ids instead of id because of the way Typeform represents multiple
+      #   choice questions.
+      # @param [Integer] field_id The Typeform Field ID for the question
+      # @param [String] original_text The original text for the question before
+      #   answers are extrapolated back into the question.
+      def initialize(ids:, field_id:, original_text:)
+        @ids = ids
+        @field_id = field_id
+        @original_text = original_text
+      end
+
+      # Performs a regular expression based on the id of the question, to
+      # determine the Type of object. This information can be queried in order
+      # to allow users to handle various types of Typeform data differently.
+      def type
+        @_type ||= determine_type
+      end
+
+      # Creates a new Question with existing data from a previous question.
+      #
+      # @return [Question] Question with extrapolated text in questions and
+      #   with the answer to the question as an attribute.
+      def self.with_response_data(question:, text:, answer:)
+        question.dup.tap do |new_question|
+          new_question.answer = answer
+          new_question.text = text
+        end.freeze
+      end
+
+      private
+
+      def determine_type
+        detected_type = ids.map { |id| id.split("_")[0] }.uniq
+        return detected_type.first if detected_type.size == 1
+        raise StandardError, "Cannot detect type of question ids #{ids}"
+      end
+    end
+  end
+end

data/lib/typed_form/version.rb

@@ -1,3 +1,4 @@
 module TypedForm
-  VERSION = "0.0.4"
+  # Up-to-date version of gem.
+  VERSION = "0.1.0"
 end

data/lib/typed_form/webhook.rb

@@ -0,0 +1,47 @@
+module TypedForm
+  # Methods used for handling incoming webhook events with data using the
+  # Typeform Webhook JSON schema.
+  #
+  # @see https://www.typeform.com/help/webhooks/ Typeform Webhook Docs
+  #
+  # @attr_reader [String] json JSON data from an incoming Typeform Webhook
+  class Webhook
+    extend Forwardable
+
+    # @!method form_response
+    #   @return [Arendelle] An immutable representation of the Webhook JSON
+    #     form_response field.
+    def_delegators :parsed_json, :form_response
+
+    # @!method form_id
+    #   @return [String] The form ID from the webhook submission.
+    def_delegators :form_response, :form_id
+    attr_reader :json
+
+    # Creates a new webhook object from an incoming Typeform Data stream.
+    # @param [String] json JSON Data from a Typeform Webhook
+    def initialize(json: json)
+      @json = json.freeze
+    end
+
+    # Retrieves the Token from the Webhook JSON data.
+    #
+    # @return [String] Unique token for the form submission.
+    def form_token
+      form_response.token
+    end
+
+    # Retrieves the Form ID from the Webhook JSON data.
+    #
+    # @return [Integer] Typeform Form ID for the Webhook.
+    def form_id
+      form_response.form_id
+    end
+
+    private
+
+    def parsed_json
+      @_parsed_json ||= JSON.parse(json, object_class: Arendelle)
+    end
+  end
+end

data/lib/typed_form.rb

@@ -1,12 +1,16 @@
 require "httparty"
 require "forwardable"
 require "arendelle"
-require "typed_form/client"
-require "typed_form/json_response_handler"
-require "typed_form/form_response"
-require "typed_form/question"
-require "typed_form/form_answers"
+require "typed_form/api/client"
+require "typed_form/form_data/parsed_json"
+require "typed_form/form_data/question"
+require "typed_form/form_data/answers"
+require "typed_form/form_data/form_submission"
+require "typed_form/form"
+require "typed_form/webhook"
 require "typed_form/version"
 
+# A collection of value objects and utilities for working with data fetched
+# or cached from the Typeform Data API.
 module TypedForm
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typed_form
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors:
 - Rob Cole
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-03-10 00:00:00.000000000 Z
+date: 2017-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -134,12 +134,14 @@ files:
 - bin/console
 - bin/setup
 - lib/typed_form.rb
-- lib/typed_form/client.rb
-- lib/typed_form/form_answers.rb
-- lib/typed_form/form_response.rb
-- lib/typed_form/json_response_handler.rb
-- lib/typed_form/question.rb
+- lib/typed_form/api/client.rb
+- lib/typed_form/form.rb
+- lib/typed_form/form_data/answers.rb
+- lib/typed_form/form_data/form_submission.rb
+- lib/typed_form/form_data/parsed_json.rb
+- lib/typed_form/form_data/question.rb
 - lib/typed_form/version.rb
+- lib/typed_form/webhook.rb
 homepage: https://github.com/useed/typed_form
 licenses:
 - MIT

data/lib/typed_form/client.rb

@@ -1,35 +0,0 @@
-module TypedForm
-  class Client
-    attr_reader :api_key
-
-    include HTTParty
-
-    def initialize(api_key:)
-      @api_key = api_key
-    end
-
-    def forms_by_id(form_id:, **query_params)
-      url_params = query_params.map { |k, v| "#{k}=#{v}" }
-      request_url = [form_id, authenticated_slug(url_params)].join("?")
-      get(request_url).body
-    end
-
-    def find_form_by(form_id:, token:, **query_params)
-      forms_by_id(form_id: form_id, token: token, **query_params)
-    end
-
-    private
-
-    def get(slug)
-      self.class.get(base_url + slug)
-    end
-
-    def base_url
-      "https://api.typeform.com/v1/form/"
-    end
-
-    def authenticated_slug(url_params)
-      ["key=#{api_key}", url_params].join("&")
-    end
-  end
-end

data/lib/typed_form/form_answers.rb

@@ -1,66 +0,0 @@
-module TypedForm
-  class FormAnswers
-    extend Forwardable
-
-    def_delegators :response, :answers, :metadata, :token
-    def_delegators :metadata, :date_submit
-
-    attr_reader :response, :input_questions, :original_questions
-
-    def self.collate(response:, input_questions:, original_questions:)
-      new(response: response,
-          input_questions: input_questions,
-          original_questions: original_questions).questions
-    end
-
-    def initialize(response:, input_questions:, original_questions:)
-      @response = response
-      @input_questions = input_questions
-      @original_questions = original_questions
-    end
-
-    def questions
-      @_questions ||= build_questions
-    end
-
-    private
-
-    def build_questions
-      input_questions.map do |question|
-        Question.with_response_data(
-          question: question,
-          answer: answers_for(question.ids),
-          text: extrapolated_question_text(question)
-        )
-      end
-    end
-
-    def answers_for(ids)
-      id_answers = ids.map { |id| find_answer_by_id(id) }.compact
-      return if id_answers.size.zero?
-      id_answers.join(", ")
-    end
-
-    def extrapolated_question_text(question)
-      regex = %r(\{\{answer_(\d+)\}\})
-      id_match = question.original_text.match(regex)
-      return question.original_text unless id_match
-
-      question.original_text.gsub(regex, find_answer_by_field_id(id_match[1]))
-    end
-
-    def find_answer_by_field_id(id)
-      fields = original_questions.select do |question|
-        question.field_id == id.to_i
-      end
-
-      answers_found = fields.map { |field| find_answer_by_id(field.id) }.compact
-      return find_answer_by_id(fields.first.id) if answers_found.size == 1
-      raise ArgumentError, "Cannot find single answer with field ID ##{id}"
-    end
-
-    def find_answer_by_id(id)
-      answers.instance_variable_get("@#{id}")
-    end
-  end
-end

data/lib/typed_form/form_response.rb

@@ -1,52 +0,0 @@
-module TypedForm
-  class FormResponse
-    attr_reader :parsed_questions, :parsed_response
-
-    def initialize(parsed_questions:, parsed_response:)
-      @parsed_questions = parsed_questions
-      @parsed_response = parsed_response
-    end
-
-    def questions_and_answers
-      FormAnswers.collate(response: parsed_response,
-                          input_questions: questions,
-                          original_questions: parsed_questions)
-    end
-
-    def questions
-      @_questions ||= build_questions
-    end
-
-    def question_ids
-      questions.flat_map(&:ids)
-    end
-
-    def question_texts
-      questions.map(&:original_text).uniq
-    end
-
-    private
-
-    def question_for_grouped(grouped_questions)
-      question_texts = grouped_questions.map(&:question)
-      return question_texts.first if question_texts.uniq.size == 1
-      raise ArgumentError, "Grouped questions do not have matching text"
-    end
-
-    def answerable_questions
-      parsed_questions
-        .reject { |q| q.id.match /(hidden|legal|statement|group)/ }
-        .group_by(&:field_id)
-    end
-
-    def build_questions
-      answerable_questions.map do |field_id, grouped_questions|
-        Question.new(
-          ids: grouped_questions.map(&:id),
-          field_id: field_id,
-          original_text: question_for_grouped(grouped_questions)
-        ).freeze
-      end
-    end
-  end
-end

data/lib/typed_form/json_response_handler.rb

@@ -1,16 +0,0 @@
-module TypedForm
-  class JSONResponseHandler
-    extend Forwardable
-    attr_reader :json
-
-    def_delegators :parsed_json, :questions, :responses
-
-    def initialize(json)
-      @json = json
-    end
-
-    def parsed_json
-      @_parsed_json ||= JSON.parse(json, object_class: Arendelle)
-    end
-  end
-end

data/lib/typed_form/question.rb

@@ -1,42 +0,0 @@
-module TypedForm
-  class Question
-    attr_reader :ids, :field_id, :original_text
-    attr_accessor :answer, :text
-
-    def initialize(ids:, field_id:, original_text:)
-      @ids = ids
-      @field_id = field_id
-      @original_text = original_text
-    end
-
-    def add_response_data(answer:, text:)
-      @answer = answer
-      @text = text
-    end
-
-    def type
-      @_type ||= determine_type
-    end
-
-    def type_for_grouped(grouped_questions)
-      types = questions.map(&:type)
-      return types.first if types.uniq.size == 1
-      raise ArgumentError, "Grouped questions do not have matching types"
-    end
-
-    def self.with_response_data(question:, text:, answer:)
-      question.dup.tap do |new_question|
-        new_question.answer = answer
-        new_question.text = text
-      end.freeze
-    end
-
-    private
-
-    def determine_type
-      detected_type = ids.map { |id| id.split("_")[0] }.uniq
-      return detected_type.first if detected_type.size == 1
-      raise StandardError, "Cannot detect type of question ids #{ids}"
-    end
-  end
-end