vworkapp_ruby 0.1.0 → 0.7.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    vworkapp_ruby (0.0.1)
+    vworkapp_ruby (0.1.0)
       gcoder
       httparty
 

data/README.md

@@ -1,18 +1,85 @@
-# vWorkApp
+# vWorkApp API's Ruby Wrapper
 
-This is a wrapper around vWorkApp's API. Go on! Use it!
+This is a ruby wrapper around vWorkApp's developer API. You can use it to create, find, update, and delete vWorkApp's jobs, customers, and users from your account.
 
-    VWorkApp::Job.api_key = "MY_API_KEY"
-    jobs = VWorkApp::Job.find(:worker_id => 1971, :state => "not_started")
+Although vWorkApp's API can be accessed directly through HTTP+XML this wrapper makes it easier and quicker for ruby developers to dive into using vWorkApp's API.
 
-## Todo
+## Installation
 
-- Handle paging
+    gem install vworkapp_ruby
 
-- Broken API bits:
-    * What's find(:search) for??. 
-    * Why can't I filter by template?
-    
-- Missing job.actual_duration, job.actual_start_at
+Or if you're using a Gemfile, include the following line:
 
-- Should have connivence method to lookup a customer from a job
+    gem 'vworkapp_ruby'
+
+## Usage
+
+Before you use the API you need to specify your API Key. If you don't have an API Key then contact support@vworkapp.com to be given one.
+
+    VW.api_key = "MY_API_KEY"
+  
+You can create a job in vWorkApp: 
+
+    job = VW::Job.new(
+      :customer_name => "ACME Baking", 
+      :template_name => "Standard Booking",
+      :planned_duration => 10 * MIN,
+      :steps => [
+        {:name => "Start", :location => {:formatted_address => "880 Harrison St, SF, USA", :lat => 37.779536, :lng => -122.401503}},
+        {:name => "End", :location => VW::Location.from_address("201 1st Street, SF", :us).attributes}
+      ],
+      :custom_fields => [
+        :name => "Note", :value => "Hi There!"
+      ]
+    )
+    job.create
+
+Search for jobs:
+
+    jobs = VW::Job.find(:state => "not_started")
+    jobs.each { |job| puts job.customer_name }
+
+Update jobs:
+
+    job = VW::Job.find(101) # assuming a job with this ID exists already
+    job.steps.first.location = VW::Location.from_address("101 1st Street, SF", :us)
+    job.update
+
+And delete them:
+
+    job = VW::Job.find(101) # assuming a job with this ID exists already
+    job.delete
+
+Full documentation on the API can be found [here](http://api.vworkapp.com/api/).
+
+## Future Work / Improvements
+
+- The wrapper doesn't handle paging of search results yet.
+
+- Proof-of-delivery needs to be added.
+
+- Base classes could be refactored out into their own gem and made a little more generic.
+
+## License
+
+This API wrapper is published under the MIT License.
+
+    Copyright (C) 2012 vWorkApp Inc.
+
+    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/examples/example_1.rb

@@ -0,0 +1,32 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib') unless $LOAD_PATH.include?(File.dirname(__FILE__) + '/../lib')
+
+# -------------
+# Example 1: Create a job
+# -------------
+
+require "rubygems"
+require "vworkapp_ruby"
+
+MIN = 60
+
+VWorkApp.api_key = "MY_API_KEY"
+
+puts "vWorkApp - Create Job"
+puts "---------------------"
+
+job = VW::Job.new(
+  :customer_name => "ACME Baking", 
+  :template_name => "Standard Booking",
+  :planned_duration => 10 * MIN,
+  :steps => [
+    {:name => "Start", :location => {:formatted_address => "880 Harrison St, SF, USA", :lat => 37.779536, :lng => -122.401503}},
+    {:name => "End", :location => VW::Location.from_address("201 1st Street, SF", :us).attributes}
+  ],
+  :custom_fields => [
+    :name => "Note", :value => "Hi There!"
+  ]
+)
+
+job = job.create
+
+puts "Job Created!. Check out the job in vWorkApp with id: #{job.id}"

data/examples/example_2.rb

@@ -0,0 +1,23 @@
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib') unless $LOAD_PATH.include?(File.dirname(__FILE__) + '/../lib')
+
+# -------------
+# Example 2: Print each worker's jobs
+# -------------
+require "rubygems"
+require "vworkapp_ruby"
+
+VW.api_key = "MY_API_KEY"
+
+puts "vWorkApp - List of jobs"
+puts "----------------------------"
+
+workers = VW::Worker.find
+
+workers.each do |worker|
+  puts "Worker: #{worker.name}"
+  jobs = VW::Job.find(:worker_id => worker.id, :state => "not_started")
+  jobs.each do |job|
+    puts "\t #{job.third_party_id || job.id}, #{job.customer_name}, #{job.template_name}"
+  end
+  puts "----------------------------"
+end

data/examples/example_3/Gemfile

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+gem 'vworkapp_ruby'
+gem 'sinatra'
+gem 'haml'

data/examples/example_3/Gemfile.lock

@@ -0,0 +1,35 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    gcoder (0.12.1)
+      hashie
+      ruby-hmac
+      yajl-ruby
+    haml (3.1.4)
+    hashie (1.2.0)
+    httparty (0.8.1)
+      multi_json
+      multi_xml
+    multi_json (1.0.4)
+    multi_xml (0.4.1)
+    rack (1.4.0)
+    rack-protection (1.2.0)
+      rack
+    ruby-hmac (0.4.0)
+    sinatra (1.3.2)
+      rack (~> 1.3, >= 1.3.6)
+      rack-protection (~> 1.2)
+      tilt (~> 1.3, >= 1.3.3)
+    tilt (1.3.3)
+    vworkapp_ruby (0.1.0)
+      gcoder
+      httparty
+    yajl-ruby (1.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  haml
+  sinatra
+  vworkapp_ruby

data/examples/example_3/README.md

@@ -0,0 +1,26 @@
+# Example 3: Worker Map
+
+This example creates a web server on your local computer that shows the location of each vWorkApp worker on a map, along with  
+
+## Installation and Usage
+
+If you aren't already using bundler, install it here:
+
+    sudo gem install bundler
+  
+Open <code>server.rb</code> and replace MY\_API\_KEY with your own vWorkApp API Key. 
+
+    VW.api_key = "MY_API_KEY"
+
+And open <code>/views/index.haml</code> and replace MY\_GOOGLE\_API\_KEY with your own Google API Key. If you don't have one it can be obtained here: http://code.google.com/apis/maps/signup.html  
+
+    %script{:src => "http://maps.googleapis.com/maps/api/js?key=MY_GOOGLE_API_KEY&sensor=false", :type => "text/javascript"}
+
+Then run:
+
+    bundle install
+    ruby server
+
+Finally, open your web browser and go to:
+
+    http://localhost:4567

data/examples/example_3/public/style.css

@@ -0,0 +1,25 @@
+html { height: 100% }
+
+body { height: 100%; margin: 0; padding: 0 }
+
+#map_canvas { height: 100% }
+
+.job {
+  font: 12px arial,sans-serif;
+  color: #333;
+  padding: 10px 0px; 
+  border-bottom: dashed 1px #ddd;
+}
+
+h1.infobox {
+  font: 11px arial,sans-serif;
+  font-weight: bold;
+  color: #999;
+  margin: 0px; 
+  border-bottom: solid 1px #ddd;
+}
+
+.job .time {
+  color: #e22;
+  padding-right: 10px;
+}

data/examples/example_3/server.rb

@@ -0,0 +1,41 @@
+require "rubygems"
+require "sinatra"
+require "vworkapp_ruby"
+require "json"
+require "haml"
+
+VW.api_key = "MY_API_KEY"
+
+get '/' do
+  @workers = VW::Worker.find
+  haml :index
+end
+
+helpers do
+
+  def job_json(workers)
+    data = @workers.map do |w|
+      next unless w.latest_telemetry
+
+      jobs = VW::Job.find(:worker_id => w.id, :state => "started")
+
+      jobs_html = jobs.inject("<h1 class='infobox'>ACTIVE JOBS:</h1>") do |str, job| 
+        str << <<-EOL
+          <div class="job">
+            <span class="time">#{job.planned_start_at.strftime("%H:%M")}</span> #{job.customer_name}, #{job.template_name}
+          </div>
+        EOL
+      end
+
+      {
+        :lat =>  w.latest_telemetry.lat, 
+        :lng =>  w.latest_telemetry.lng, 
+        :name => w.name,
+        :jobs => jobs_html 
+      }
+    end
+    
+    data.to_json
+  end
+
+end

data/examples/example_3/views/index.haml

@@ -0,0 +1,47 @@
+!!! 5
+%html
+  %head
+    %meta{:content => "initial-scale=1.0, user-scalable=no", :name => "viewport"}/
+    
+    %link{:rel => "StyleSheet", :href => "/style.css", :type => "text/css" }
+        
+    %script{:src => "http://maps.googleapis.com/maps/api/js?key=MY_GOOGLE_API_KEY&sensor=false", :type => "text/javascript"}
+    
+    :javascript
+      infoWindow = new google.maps.InfoWindow();
+
+      function makeMarker(data, map) {
+        var marker = new google.maps.Marker({
+          position: new google.maps.LatLng(data.lat, data.lng),
+          map: map,
+          icon: 'truck.png'
+        });                
+
+        google.maps.event.addListener(marker, 'click', function() {
+          infoWindow.close();
+          infoWindow.setContent(data.jobs)
+          infoWindow.open(map, marker);
+        });
+      }
+    
+      function initialize() {
+        
+        var myOptions = {
+          center: new google.maps.LatLng(37.779536,-122.401503),
+          zoom: 12,
+          mapTypeId: google.maps.MapTypeId.ROADMAP
+        };
+        
+        var map = new google.maps.Map(document.getElementById("map_canvas"), myOptions);
+        
+        workers = #{job_json(@workers)}
+        
+        for (var i = 0; i < workers.length; i++) {
+          if (workers[i] != null)
+            makeMarker(workers[i], map);
+        }
+        
+      }
+    
+  %body{:onload => "initialize()"}
+    #map_canvas{:style => "width:100%; height:100%"}

data/lib/vworkapp_ruby.rb

@@ -1,11 +1,21 @@
-require 'vworkapp_ruby/base'
+require 'httparty'
+require 'active_support/core_ext/hash'
+require 'active_model'
+
+require 'vworkapp_ruby/base/base'
+require 'vworkapp_ruby/base/resource'
+require 'vworkapp_ruby/base/response_error'
+
 require 'vworkapp_ruby/location'
+require 'vworkapp_ruby/step'
+require 'vworkapp_ruby/contact'
+require 'vworkapp_ruby/telemetry'
+require 'vworkapp_ruby/custom_field'
 require 'vworkapp_ruby/job'
 require 'vworkapp_ruby/worker'
 require 'vworkapp_ruby/customer'
-require 'vworkapp_ruby/response_error'
 # require 'vworkapp/proof_of_delivery'
 
-require 'vworkapp_ruby/httparty_monkey_patch'
+require 'vworkapp_ruby/base/httparty_monkey_patch'
 
 VW = VWorkApp

data/lib/vworkapp_ruby/base/base.rb

@@ -0,0 +1,173 @@
+require 'set'
+
+module VWorkApp
+  class Base
+    include ActiveModel::Serializers::JSON
+    include ActiveModel::Serializers::Xml
+    include ActiveModel::Validations
+
+    def initialize(attributes = {})
+      self.attributes = attributes
+    end
+
+    # -----------------
+    # Hattr Methods
+    # ----------------
+
+    def self.hattr_reader(*hattrs)
+      hattrs.each do |hattr|
+        self.read_hattrs << hattr
+        attr_reader(hattr.is_a?(Hash) ? hattr.keys.first : hattr)
+      end
+    end
+
+    def self.hattr_writer(*hattrs)
+      hattrs.each do |hattr|
+        self.write_hattrs << hattr
+        attr_writer(hattr.is_a?(Hash) ? hattr.keys.first : hattr)
+      end
+    end
+    
+    def self.hattr_accessor(*hattrs)
+      hattr_reader(*hattrs)
+      hattr_writer(*hattrs)
+    end
+
+    def self.write_hattrs
+      @write_hattrs ||= Set.new
+    end
+    def write_hattrs
+      self.class.write_hattrs
+    end
+
+    def self.read_hattrs
+      @read_hattrs ||= Set.new
+    end
+    def read_hattrs
+      self.class.read_hattrs
+    end
+
+    def self.hattrs
+      read_hattrs + write_hattrs
+    end
+    def hattrs
+      self.class.hattrs
+    end
+
+    # -------------------
+    # Attributes Methods
+    # -------------------
+  
+    def attributes
+      extract_attributes(hattrs)
+    end
+
+    def read_attributes
+      extract_attributes(read_hattrs)
+    end
+    
+    def write_attributes
+      extract_attributes(write_hattrs)
+    end
+
+    def attributes=(hash)
+      inject_attributes(hattrs, hash)
+    end
+
+    def write_attributes=(hash)
+      inject_attributes(write_hattrs, hash)
+    end
+
+    def read_attributes=(hash)
+      inject_attributes(read_hattrs, hash)
+    end
+
+    # -----------------
+    # Misc Methods
+    # -----------------
+
+    def validate_and_raise
+      raise Exception.new(self.errors.full_messages.join("\n")) unless valid?
+    end
+
+    def attributes_eql?(other, *test_attrs)
+      test_attrs.each do |attribute|
+        return false unless self.send(attribute.to_sym) == other.send(attribute.to_sym)
+      end
+      true
+    end
+
+  private
+      
+    def extract_attributes(hattrs)
+      attr = hattrs.map do |hattr|
+        hattr = hattr.keys.first if hattr.is_a?(Hash)
+        [hattr.to_s, send(hattr)]
+      end
+      Hash[attr]
+    end
+
+    def inject_attributes(hattrs, hash)
+      hash = Hash[hash.map { |k,v| [k.to_sym, v] }]
+
+      hattrs.each do |hattr|
+        value = case hattr
+        when Hash
+          hattr, klass = hattr.first
+          next unless hash[hattr.to_sym]
+          klass.is_a?(Array) ? hash[hattr.to_sym].map {|h| klass.first.new(h)} : klass.new(hash[hattr.to_sym])
+        else
+          next unless hash[hattr.to_sym]
+          hash[hattr.to_sym]
+        end
+        
+        set_hattr(hattr, value)
+      end
+    end
+
+    def set_hattr(hattr, value)
+      write_hattrs.include?(hattr) ? send("#{hattr}=", value) : self.instance_variable_set("@#{hattr.to_s}", value)
+    end
+
+  end
+end
+
+# -----------------
+# AM Monkey Patches. Yuk.
+# -----------------
+
+module ActiveModel::Serialization
+  def serializable_hash(options = nil)
+    options ||= {}
+
+    only   = Array.wrap(options[:only]).map(&:to_s)
+    except = Array.wrap(options[:except]).map(&:to_s)
+
+    # AF: Changed to write_attributes
+    attribute_names = write_attributes.keys.sort
+    if only.any?
+      attribute_names &= only
+    elsif except.any?
+      attribute_names -= except
+    end
+
+    method_names = Array.wrap(options[:methods]).map { |n| n if respond_to?(n.to_s) }.compact
+    Hash[(attribute_names + method_names).map { |n| [n, send(n)] }]
+  end
+end
+
+module ActiveModel::Serializers::Xml
+  class Serializer
+    def attributes_hash
+      # AF: Changed to write_attributes
+      attributes = @serializable.write_attributes
+      if options[:only].any?
+        attributes.slice(*options[:only])
+      elsif options[:except].any?
+        attributes.except(*options[:except])
+      else
+        attributes
+      end
+    end
+  end
+end