wuparty 1.0.2

data/README.rdoc

@@ -0,0 +1,92 @@
+= WuParty
+
+WuParty is a fairly lightweight wrapper for Wufoo's REST API[http://wufoo.com/docs/api/v3]
+using HTTParty[http://httparty.rubyforge.org].
+
+== API Support
+
+Wufoo's REST API supports viewing and submitting entries, filtering entries,
+viewing reports, and viewing users.
+
+This library supports all methods of Wufoo's API version 3.0.
+
+There is an older version of this library (version 0.1.x) that only supports version 2 of Wufoo's API.
+Make sure you have latest version installed (1.0.0 or higher).
+
+== Source & Download
+
+* {Homepage & Demo}[http://wuparty.71m.us]
+* {Source Code}[http://github.com/seven1m/wuparty]
+* {RDoc Documentation}[http://seven1m.github.com/wuparty]
+
+== Installation
+
+    gem install wuparty
+
+== Usage
+
+    require 'wuparty'
+
+    ACCOUNT = 'accountname'
+    API_KEY = 'AAAA-BBBB-CCCC-DDDD'
+    FORM_ID = 'my-form-id'
+
+    wufoo = WuParty.new(ACCOUNT, API_KEY)
+
+    wufoo.forms # list all accessible forms and details
+    form = wufoo.form(FORM_ID) # or details for a specific form
+
+    # query all entries
+    form.entries
+
+    # ...or filter entries (see http://wufoo.com/docs/api/v3/entries/get/#filter)
+    form.entries([['Field1', 'Is_equal_to', 'Tim']])
+
+    # To submit, use field numbers shown on the 'API Information' page in Wufoo
+    result = wufoo.submit(
+      'Field1' => 'Tim',
+      'Field2' => 'Morgan'
+    })
+    if result['Success'] == 0
+      puts result['ErrorText']
+    end
+    
+== Feedback
+
+I’d love to hear from you if you have suggestions for improvement, bug fixes, or whatever.
+Email me at mailto:tim@timmorgan.org or fork the project[http://github.com/seven1m/wuparty] and send a pull request.
+
+http://timmorgan.org
+
+== Tests
+
+To run the tests, you must create a form called "Test Form" and pass in its id via the
+ENV variable WUFOO_FORM_ID. Give the form a standard name and address field.
+Make the name field required. Then run:
+
+    WUFOO_ACCOUNT=accountname \
+    WUFOO_API_KEY=AAAA-BBBB-CCCC-DDDD \
+    WUFOO_FORM_ID=test-form \
+    ruby -rrubygems test/wuparty_test.rb
+
+== License
+
+Copyright (c) 2010 Tim Morgan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/wuparty.rb

@@ -0,0 +1,339 @@
+require 'httparty'
+gem 'multipart-post'
+require 'net/http/post/multipart'
+gem 'mime-types'
+require 'mime/types'
+
+# multipart POST support from David Balater's fork of HTTParty:
+# http://github.com/dbalatero/httparty
+# :stopdoc:
+module HTTParty
+  module ClassMethods
+    def post(path, options={})
+      klass = options[:multipart] ? Net::HTTP::Post::Multipart : Net::HTTP::Post
+      perform_request klass, path, options
+    end
+  end
+  class Request
+    SupportedHTTPMethods << Net::HTTP::Post::Multipart
+    private
+      def setup_raw_request
+        if multipart?
+          @file_handles = []
+          io_objects = {}
+
+          options[:multipart].each do |field_name, info|
+            fp = File.open(info[:path])
+            @file_handles << fp
+
+            io_objects[field_name] = UploadIO.new(fp,
+                                                  info[:type],
+                                                  info[:path])
+          end
+
+          if options[:body]
+            options[:body].each do |field_name, value|
+              io_objects[field_name] = value
+            end
+          end
+
+          @raw_request = http_method.new(uri.request_uri,
+                                         io_objects)
+
+          # We have to duplicate and merge the headers set by the
+          # multipart object to make sure that Net::HTTP 
+          # doesn't override them down the line when it calls
+          # initialize_http_header.
+          #
+          # Otherwise important headers like Content-Length,
+          # Accept, and Content-Type will be deleted.
+          original_headers = {}
+          @raw_request.each do |key, value|
+            original_headers[key] = value
+          end
+
+          options[:headers] ||= {}
+          original_headers.merge!(options[:headers])
+          options[:headers] = original_headers
+        else
+          @raw_request = http_method.new(uri.request_uri)
+          @raw_request.body = body if body
+        end
+
+        @raw_request.initialize_http_header options[:headers]
+        @raw_request.basic_auth(username, password) if options[:basic_auth]
+      end
+      def multipart?
+        Net::HTTP::Post::Multipart == http_method
+      end
+  end
+end
+# :startdoc:
+
+class WuParty
+  include HTTParty
+  format :json
+
+  VERSION = '1.0.2'
+
+  # Represents a general error connecting to the Wufoo service
+  class ConnectionError < RuntimeError; end
+
+  # Represents a specific error returned from Wufoo.
+  class HTTPError < RuntimeError
+    def initialize(code, message) # :nodoc:
+      @code = code
+      super(message)
+    end
+
+    # Error code
+    attr_reader :code
+  end
+
+  ENDPOINT    = 'https://%s.wufoo.com/api/v3'
+  API_VERSION = '3.0'
+
+  # Create a new WuParty object
+  def initialize(account, api_key)
+    @account = account
+    @api_key = api_key
+    @field_numbers = {}
+  end
+
+  # Returns list of forms and details accessible by the user account.
+  def forms
+    get(:forms)['Forms'].map do |details|
+      Form.new(details['Url'], :party => self, :details => details)
+    end
+  end
+
+  # Returns list of reports and details accessible by the user account.
+  def reports
+    get(:reports)['Reports'].map do |details|
+      Report.new(details['Url'], :party => self, :details => details)
+    end
+  end
+
+  # Returns list of users and details.
+  def users
+    get(:users)['Users'].map do |details|
+      User.new(details['Url'], :party => self, :details => details)
+    end
+  end
+
+  # Returns details about the specified form.
+  def form(form_id)
+    if f = get("forms/#{form_id}")['Forms']
+      Form.new(f.first['Url'], :party => self, :details => f.first)
+    end
+  end
+
+  # Returns details about the specified report.
+  def report(report_id)
+    if r = get("reports/#{report_id}")['Reports']
+      Form.new(r.first['Url'], :party => self, :details => r.first)
+    end
+  end
+
+  def get(method, options={}) # :nodoc:
+    options.merge!(:basic_auth => {:username => @api_key})
+    url = "#{base_url}/#{method}.json"
+    result = self.class.get(url, options)
+    if result.is_a?(String)
+      raise ConnectionError, result
+    elsif result['HTTPCode']
+      raise HTTPError.new(result['HTTPCode'], result['Text'])
+    else
+      result
+    end
+  end
+
+  def post(method, options={}) # :nodoc:
+    options.merge!(:basic_auth => {:username => @api_key})
+    url = "#{base_url}/#{method}.json"
+    result = self.class.post(url, options)
+    if result.is_a?(String)
+      raise ConnectionError, result
+    elsif result['HTTPCode']
+      raise HTTPError.new(result['HTTPCode'], result['Text'])
+    else
+      result
+    end
+  end
+
+  private
+
+    def base_url
+      ENDPOINT % @account
+    end
+
+  public
+
+  # ----------
+
+  class Entity # :nodoc:
+    include HTTParty
+    format :json
+
+    def initialize(id, options)
+      @id = id
+      if options[:party]
+        @party = options[:party]
+      elsif options[:account] and options[:api_key]
+        @party = WuParty.new(options[:account], options[:api_key])
+      else
+        raise WuParty::InitializationException, "You must either specify a :party object or pass the :account and :api_key options. Please see the README."
+      end
+      @details = options[:details]
+    end
+
+    attr_accessor :details
+  end
+
+  # Wraps an individual Wufoo Form.
+  # == Instantiation
+  # There are two ways to instantiate a Form object:
+  # 1. Via the parent WuParty object that represents the account.
+  # 2. Via the WuParty::Form class directly.
+  #   wufoo = WuParty.new(ACCOUNT, API_KEY)
+  #   form = wufoo.form(FORM_ID)
+  #   # or...
+  #   form = WuParty::Form.new(FORM_ID, :account => ACCOUNT, :api_key => API_KEY)
+  # The first technique makes a call to the Wufoo API to get the form details,
+  # while the second technique lazily loads the form details, once something is accessed via [].
+  # == \Form Details
+  # Access form details like it is a Hash, e.g.:
+  #   form['Name']
+  #   form['RedirectMessage']
+  class Form < Entity
+    # Returns field details for the form.
+    def fields
+      @party.get("forms/#{@id}/fields")['Fields']
+    end
+
+    # Access form details.
+    def [](id)
+      @details ||= @party.form(@id)
+      @details[id]
+    end
+
+    # Returns fields and subfields, as a flattened array, e.g.
+    #   [{'ID' => 'Field1', 'Title' => 'Name - First', 'Type' => 'shortname', 'Required' => true }, # (subfield)
+    #    {'ID' => 'Field2', 'Title' => 'Name - Last',  'Type' => 'shortname', 'Required' => true }, # (subfield)
+    #    {'ID' => 'Field3', 'Title' => 'Birthday',     'Type' => 'date',      'Required' => flase}] # (field)
+    # By default, only fields that can be submitted are returned. Pass *true* as the first arg to return all fields.
+    def flattened_fields(all=false)
+      flattened = []
+      fields.each do |field|
+        next unless all or field['ID'] =~ /^Field/
+        if field['SubFields']
+          field['SubFields'].each do |sub_field|
+            flattened << {'ID' => sub_field['ID'], 'Title' => field['Title'] + ' - ' + sub_field['Label'], 'Type' => field['Type'], 'Required' => field['IsRequired'] == '1'}
+          end
+        else
+          flattened << {'ID' => field['ID'], 'Title' => field['Title'], 'Type' => field['Type'], 'Required' => field['IsRequired'] == '1'}
+        end
+      end
+      flattened
+    end
+
+    # Return entries already submitted to the form.
+    #
+    # If you need to filter entries, pass an array as the first argument:
+    #   entries([[field_id, operator, value], ...])
+    # e.g.:
+    #   entries([['EntryId', 'Is_after', 12], ['EntryId', 'Is_before', 17]])
+    #   entries([['Field1', 'Is_equal', 'Tim']])
+    # The second arg is the match parameter (AND/OR) and defaults to 'AND', e.g.
+    #   entries([['Field2', 'Is_equal', 'Morgan'], ['Field2', 'Is_equal', 'Smith']], 'OR')
+    # See http://wufoo.com/docs/api/v3/entries/get/#filter for details
+    def entries(filters=[], filter_match='AND')
+      if filters.any?
+        options = {'match' => filter_match}
+        filters.each_with_index do |filter, index|
+          options["Filter#{index+1}"] = filter.join(' ')
+        end
+        options = {:query => options}
+      else
+        options = {}
+      end
+      @party.get("forms/#{@id}/entries", options)['Entries']
+    end
+
+    # Submit form data to the form.
+    # Pass data as a hash, with field ids as the hash keys, e.g.
+    #   submit('Field1' => 'Tim', 'Field2' => 'Morgan')
+    # Return value is a Hash that includes the following keys:
+    # * Status
+    # * ErrorText
+    # * FieldErrors
+    # You must submit values for required fields (including all sub fields),
+    # and dates must be formatted as <tt>YYYYMMDD</tt>.
+    def submit(data)
+      options = {}
+      data.each do |key, value|
+        if value.is_a?(Hash)
+          type = MIME::Types.of(value[:path]).first.content_type rescue 'application/octet-stream'
+          options[:multipart] ||= {}
+          options[:multipart][key] = {:type => type, :path => value[:path]}
+        else
+          options[:body] ||= {}
+          options[:body][key] = value
+        end
+      end
+      @party.post("forms/#{@id}/entries", options)
+    end
+
+    # Returns comment details for the form.
+    # See Wufoo API documentation for possible options,
+    # e.g. to filter comments for a specific form entry:
+    #   form.comments('entryId' => 123)
+    def comments(options={})
+      options = {:query => options} if options.any?
+      @party.get("forms/#{@id}/comments", options)['Comments']
+    end
+  end
+
+  # Wraps an individual Wufoo Report.
+  # == Instantiation
+  # There are two ways to instantiate a Report object:
+  # 1. Via the parent WuParty object that represents the account.
+  # 2. Via the WuParty::Report class directly.
+  #   wufoo = WuParty.new(ACCOUNT, API_KEY)
+  #   report = wufoo.report(REPORT_ID)
+  #   # or...
+  #   report = WuParty::Report.new(REPORT_ID, :account => ACCOUNT, :api_key => API_KEY)
+  # The first technique makes a call to the Wufoo API to get the report details,
+  # while the second technique lazily loads the report details, once something is accessed via [].
+  # == \Report Details
+  # Access report details like it is a Hash, e.g.:
+  #   report['Name']
+  class Report < Entity
+    # Access report details.
+    def [](id)
+      @details ||= @party.report(@id)
+      @details[id]
+    end
+
+    # Returns field details for the report
+    def fields
+      @party.get("reports/#{@id}/fields")['Fields']
+    end
+
+    # Returns widget details for the report
+    def widgets
+      @party.get("reports/#{@id}/widgets")['Widgets']
+    end
+  end
+
+  # Wraps an individual Wufoo User.
+  class User < Entity
+
+    # Access user details.
+    def [](id)
+      @details ||= @party.report(@id)
+      @details[id]
+    end
+
+  end
+end

data/test/wuparty_test.rb

@@ -0,0 +1,100 @@
+require File.dirname(__FILE__) + '/../lib/wuparty'
+require 'test/unit'
+
+class WuPartyTest < Test::Unit::TestCase
+
+  # Must create a form called "Test Form" and pass in its id
+  # via the ENV variable WUFOO_FORM_ID.
+  # Give the form standard name and address fields.
+  # Make the name field required.
+
+  def setup
+    if ENV['WUFOO_ACCOUNT'] and ENV['WUFOO_API_KEY'] and ENV['WUFOO_FORM_ID']
+      @wufoo = WuParty.new(ENV['WUFOO_ACCOUNT'], ENV['WUFOO_API_KEY'])
+      @form_id = ENV['WUFOO_FORM_ID']
+    else
+      puts 'Must set WUFOO_ACCOUNT, WUFOO_API_KEY and WUFOO_FORM_ID env variables before running.'
+      exit(1)
+    end
+  end
+
+  def test_forms
+    assert @wufoo.forms
+  end
+
+  def test_form
+    form = @wufoo.form(@form_id)
+    assert form
+    assert_equal 'Test Form', form['Name']
+  end
+
+  def test_form_by_hash
+    hash = @wufoo.form(@form_id)['Hash']
+    assert @wufoo.form(hash)
+  end
+
+  def test_form_directly
+    form = WuParty::Form.new(@form_id, :account => ENV['WUFOO_ACCOUNT'], :api_key => ENV['WUFOO_API_KEY'])
+    assert_equal 'Test Form', form['Name']
+  end
+
+  def test_non_existent_form
+    assert_raise WuParty::HTTPError do
+      @wufoo.form('does-not-exist')
+    end
+  end
+
+  def test_reports
+    assert @wufoo.reports
+  end
+
+  def test_users
+    assert @wufoo.users
+  end
+
+  def test_form_fields
+    form = @wufoo.form(@form_id)
+    field_names = form.fields.map { |f| f['Title'] }
+    assert field_names.include?('Name')
+    assert field_names.include?('Address')
+  end
+
+  def test_form_submit
+    form = @wufoo.form(@form_id)
+    result = form.submit('Field1' => 'Tim', 'Field2' => 'Morgan', 'Field3' => '4010 W. New Orleans', 'Field5' => 'Broken Arrow', 'Field6' => 'OK', 'Field7' => '74011')
+    assert_equal 1, result['Success']
+    assert result['EntryId']
+    assert result['EntryLink']
+  end
+
+  def test_form_submit_error
+    form = @wufoo.form(@form_id)
+    # test a form error -- non-existent field
+    result = form.submit('Field1' => 'Tim', 'Field2' => 'Morgan', 'Field100' => 'Foobar')
+    assert_equal 0, result['Success']
+    assert result['ErrorText']
+    assert_equal [], result['FieldErrors']
+    # test a field error -- nothing in a required field
+    result = form.submit('Field2' => 'Morgan')
+    assert_equal 0, result['Success']
+    assert_equal 1, result['FieldErrors'].length
+    error = result['FieldErrors'].first
+    assert_equal 'Field1', error['ID']
+    assert_match /required/i, error['ErrorText']
+  end
+
+  def test_entries
+    form = @wufoo.form(@form_id)
+    form.submit('Field1' => 'Tim', 'Field2' => 'Morgan')
+    assert form.entries.last['Field1'].any?
+  end
+
+  def test_filtering_entries
+    form = @wufoo.form(@form_id)
+    form.submit('Field1' => 'Tim', 'Field2' => 'Morgan')
+    id = form.submit('Field1' => 'Jane', 'Field2' => 'Smith')['EntryId']
+    assert form.entries([['Field2', 'Is_equal_to', 'Morgan']]).any?
+    assert_equal 1, form.entries([['EntryId', 'Is_equal_to', id]]).length
+  end
+
+end

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification 
+name: wuparty
+version: !ruby/object:Gem::Version 
+  hash: 19
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 2
+  version: 1.0.2
+platform: ruby
+authors: 
+- Tim Morgan
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-09-17 00:00:00 -05:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: httparty
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 5
+        segments: 
+        - 0
+        - 6
+        - 1
+        version: 0.6.1
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: multipart-post
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 21
+        segments: 
+        - 1
+        - 0
+        - 1
+        version: 1.0.1
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: mime-types
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 47
+        segments: 
+        - 1
+        - 16
+        version: "1.16"
+  type: :runtime
+  version_requirements: *id003
+description: 
+email: tim@timmorgan.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- lib/wuparty.rb
+- test/wuparty_test.rb
+has_rdoc: true
+homepage: http://seven1m.github.com/wuparty
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Ruby wrapper for Wufoo's REST API v3.
+test_files: []
+