quickeebooks 0.0.8 → 0.0.9

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    quickeebooks (0.0.8)
+    quickeebooks (0.0.9)
       activemodel
       nokogiri
       oauth

data/README.md

@@ -22,22 +22,69 @@ Gems:
 * `nokogiri` : XML parsing
 * `active_model` : For validations
 
-## Getting Started
+## Getting Started & Initiating Authentication Flow with Intuit
 
-This library assumes you already have an OAuth token and secret. You can then initialize your `OAuth Consumer` and create a `OAuth Client` via:
+What follows is an example using Rails but the principles can be adapted to any other framework / pure Ruby.
+
+Create a Rails initializer with:
 
 ```ruby
-QB_KEY = "your-qb-key"
-QB_SECRET = "your-qb-secret"
+QB_KEY = "your apps Intuit App Key"
+QB_SECRET = "your apps Intuit Secret Key"
 
-qb_oauth_consumer = OAuth::Consumer.new(QB_KEY, QB_SECRET, {
+$qb_oauth_consumer = OAuth::Consumer.new(QB_KEY, QB_SECRET, {
     :site                 => "https://oauth.intuit.com",
     :request_token_path   => "/oauth/v1/get_request_token",
     :authorize_url        => "https://appcenter.intuit.com/Connect/Begin",
     :access_token_path    => "/oauth/v1/get_access_token"
 })
+```
+
+To start the authentication flow with Intuit you include the Intuit Javascript and on a page of your choosing you present the "Connect to Quickbooks" button by including this XHTML:
+
+
+```HTML
+<!-- somewhere in your document include the Javascript -->
+<script type="text/javascript" src="https://appcenter.intuit.com/Content/IA/intuit.ipp.anywhere.js"></script>
+
+<!-- configure the Intuit object: 'grantUrl' is a URL in your application which kicks off the flow, see below -->
+<script>
+intuit.ipp.anywhere.setup({menuProxy: '/path/to/blue-dot', grantUrl: '/path/to/your-flow-start'});
+</script>
+
+<!-- this will display a button that the user clicks to start the flow -->
+<ipp:connectToIntuit></ipp:connectToIntuit>
+```
+
+Your Controller action (the `grantUrl` above) should look like this:
+
+```ruby
+  def authenticate
+    callback = quickbooks_oauth_callback_url
+    token = $qb_oauth_consumer.get_request_token(:oauth_callback => callback)
+    session[:qb_request_token] = token
+    redirect_to("https://appcenter.intuit.com/Connect/Begin?oauth_token=#{token.token}") and return
+  end
+```
+
+Where `quickbooks_oauth_callback_url` is the absolute URL of your application that Intuit should send the user when authentication succeeeds. That action should look like:
+
+```ruby
+def oauth_callback
+	at = session[:qb_request_token].get_access_token(:oauth_verifier => params[:oauth_verifier])
+	token = at.token
+	secret = at.secret
+	realm_id = params['realmId']
+	# store the token, secret & RealmID somewhere for this user, you will need all 3 to work with Quickeebooks
+end
+```
 
-oauth_client = OAuth::AccessToken.new(qb_oauth_consumer, access_token, access_secret)
+## Creating an OAuth Access Token
+
+Once you have your users OAuth Token & Secret you can initialize your `OAuth Consumer` and create a `OAuth Client` using the `$qb_oauth_consumer` you created earlier in your Rails initializer:
+
+```ruby
+oauth_client = OAuth::AccessToken.new($qb_oauth_consumer, access_token, access_secret)
 ```
 
 ## Quickbooks Online vs Windows
@@ -46,17 +93,21 @@ IDS provides 2 APIs, one for interacting with Quickbooks Online resources and on
 
 See: https://ipp.developer.intuit.com/0010_Intuit_Partner_Platform/0050_Data_Services
 
-As of this time Quickeebooks has a little more features for Online API vs Windows API. Ultimately the Quickeebooks API should be the same and its just a matter of instantiating the correct classes.
+You will need to be aware of which flavor of the API you want to invoke.
 
 For example:
 
 ```ruby
 # Instantiate a Online API
-customer_service = Quickeebooks::Online::Service::Customer.new(oauth_client, realm_id)
+customer_service = Quickeebooks::Online::Service::Customer.new
+customer_service.access_token = oauth_client
+customer_service.realm_id = realm_id
 customer_service.list 
 
 # Instantiate a Windows API
 customer_service = Quickeebooks::Windows::Service::Customer.new(oauth_client, realm_id)
+customer_service.access_token = oauth_client
+customer_service.realm_id = realm_id
 customer_service.list 
 ```
 
@@ -65,7 +116,10 @@ All of the documentation below is geared towards the Online flavor but unless no
 Now we can initialize any of the `Service` clients:
 
 ```ruby
-customer_service = Quickeebooks::Online::Service::Customer.new(oauth_client, realm_id)
+customer_service = Quickeebooks::Online::Service::Customer.new
+customer_service.access_token = oauth_client
+customer_service.realm_id = realm_id
+customer_service.list 
 customer_service.list 
 
 # returns a `Collection` object
@@ -99,7 +153,11 @@ Pass a `Sort` object for any desired sorting or just let Intuit use the default
 Specify none of these to get the defaults:
 
 ```ruby
-customer_service = Quickeebooks::Online::Service::Customer.new(oauth_client, realm_id,)
+customer_service = Quickeebooks::Online::Service::Customer.new
+customer_service.access_token = oauth_client
+customer_service.realm_id = realm_id
+customer_service.list 
+
 # fetch all customers with default parameters (pagination, sorting, filtering)
 customers = customer_service.list
 ```
@@ -172,7 +230,11 @@ filters = []
 filters << Quickeebooks::Online::Service::Filter.new(:text, :field => 'FamilyName', :value => 'Richards')
 datetime = Time.mktime(2011, 2, 25)
 filters << Quickeebooks::Online::Service::Filter.new(:datetime, :field => 'CreateTime', :before => datetime)
-customer_service = Quickeebooks::Online::Service::Customer.new(oauth_client, realm_id)
+customer_service = Quickeebooks::Online::Service::Customer.new
+customer_service.access_token = oauth_client
+customer_service.realm_id = realm_id
+customer_service.list 
+
 customers = customer_service.list(filters)
 ```
 ## Sorting (currently only supported in the Online API)
@@ -201,7 +263,11 @@ filters << Quickeebooks::Online::Service::Filter.new(:datetime, :field => 'Creat
 
 sorter = Quickeebooks::Online::Service::Sort.new('FamilyName', 'AtoZ')
 
-customer_service = Quickeebooks::Online::Service::Customer.new(oauth_client, realm_id)
+customer_service = Quickeebooks::Online::Service::Customer.new
+customer_service.access_token = oauth_client
+customer_service.realm_id = realm_id
+customer_service.list 
+
 customers = customer_service.list(filters, 1, 30, sort)
 
 # returns
@@ -222,7 +288,11 @@ Use the `Service` instance to fetch an object by its id using the `fetch_by_id`
 
 ```ruby
 # fetch the Customer object with an id of 100
-customer_service = Quickeebooks::Online::Service::Customer.new(oauth_client, realm_id)
+customer_service = Quickeebooks::Online::Service::Customer.new
+customer_service.access_token = oauth_client
+customer_service.realm_id = realm_id
+customer_service.list 
+
 customer = customer_service.fetch_by_id(100)
 customer.name
 => John Doe
@@ -239,7 +309,11 @@ You will need make sure you supply all required fields for that Intuit object, s
 Pass an instance of your object to the `create` method on its related Service:
 
 ```ruby
-customer_service = Quickeebooks::Online::Service::Customer.new(oauth_client, realm_id)
+customer_service = Quickeebooks::Online::Service::Customer.new
+customer_service.access_token = oauth_client
+customer_service.realm_id = realm_id
+customer_service.list 
+
 customer = Quickeebooks::Online::Model::Customer.new
 customer.name = "Richard Parker"
 customer.email = "richard@example.org"
@@ -253,7 +327,11 @@ customer_service.create(customer)
 Pass an instance of your object to the `update` method on its related Service:
 
 ```ruby
-customer_service = Quickeebooks::Online::Service::Customer.new(oauth_client, realm_id)
+customer_service = Quickeebooks::Online::Service::Customer.new
+customer_service.access_token = oauth_client
+customer_service.realm_id = realm_id
+customer_service.list 
+
 customer = customer_service.fetch_by_id(100)
 customer.name = "Richard Parker"
 customer.email = "richard@example.org"

data/lib/quickeebooks/online/model/invoice_header.rb

@@ -17,6 +17,7 @@ module Quickeebooks
         xml_accessor :sales_tax_code_name, :from => 'SalesTaxCodeName'
         xml_accessor :sub_total_amount, :from => 'SubTotalAmt', :as => Float
         xml_accessor :tax_rate, :from => 'TaxRate', :as => Float
+        xml_accessor :tax_amount, :from => 'TaxAmt', :as => Float
         xml_accessor :balance, :from => 'Balance', :as => Float
         xml_accessor :total_amount, :from => 'TotalAmt', :as => Float
         xml_accessor :due_date, :from => 'DueDate', :as => Time

data/lib/quickeebooks/version.rb

@@ -1,5 +1,5 @@
 module Quickeebooks
 
-  VERSION = "0.0.8"
+  VERSION = "0.0.9"
 
 end

data/lib/quickeebooks/windows/model/address.rb

@@ -15,8 +15,8 @@ module Quickeebooks
         xml_accessor :country_sub_division_code, :from => 'CountrySubDivisionCode'
         xml_accessor :postal_code, :from => 'PostalCode'
         xml_accessor :postal_code_suffix, :from => 'PostalCodeSuffix'
-        xml_accessor :tag, :from => 'Tag'
         xml_accessor :default, :from => 'Default'
+        xml_accessor :tag, :from => 'Tag'
 
         def zip
           postal_code

data/lib/quickeebooks/windows/model/customer.rb

@@ -34,9 +34,9 @@ module Quickeebooks
         xml_accessor :type_of, :from => 'TypeOf'
         xml_accessor :name, :from => 'Name'
         xml_accessor :addresses, :from => 'Address', :as => [Quickeebooks::Windows::Model::Address]
-        xml_accessor :email, :from => 'Email', :as => Quickeebooks::Windows::Model::Email
         xml_accessor :phones, :from => 'Phone', :as => [Quickeebooks::Windows::Model::Phone]
         xml_accessor :web_site, :from => 'WebSite', :as => Quickeebooks::Windows::Model::WebSite
+        xml_accessor :email, :from => 'Email', :as => Quickeebooks::Windows::Model::Email
         xml_accessor :title, :from => 'Title'
         xml_accessor :given_name, :from => 'GivenName'
         xml_accessor :middle_name, :from => 'MiddleName'

data/lib/quickeebooks/windows/model/phone.rb

@@ -7,8 +7,8 @@ module Quickeebooks
         xml_accessor :id, :from => 'Id'
         xml_accessor :device_type, :from => 'DeviceType'
         xml_accessor :free_form_number, :from => 'FreeFormNumber'
-        xml_accessor :tag, :from => 'Tag'
         xml_accessor :default, :from => 'Default'
+        xml_accessor :tag, :from => 'Tag'
         
         def default?
           default == "true"

data/lib/quickeebooks/windows/service/customer.rb

@@ -32,7 +32,41 @@ module Quickeebooks
           </Add>
           XML
           perform_write(Quickeebooks::Windows::Model::Customer, xml)
+        end
+        
+        def update(customer)
+          # XML is a wrapped 'object' where the type is specified as an attribute
+          #    <Object xsi:type="Invoice">
+          
+          # Intuit requires that some fields are unset / do not exist.
+          customer.meta_data = nil
+          customer.external_key = nil
+
+          # unset Id fields in addresses, phones, email
+          if customer.addresses
+            customer.addresses.each {|address| address.id = nil }
+          end
+          if customer.email
+            customer.email.id = nil
+          end
+          
+          if customer.phones
+            customer.phones.each {|phone| phone.id = nil }
+          end
+          
+          if customer.web_site
+            customer.web_site.id = nil
+          end
           
+          xml_node = customer.to_xml(:name => 'Object')
+          xml_node.set_attribute('xsi:type', 'Customer')
+          xml = <<-XML
+          <Mod xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" RequestId="#{guid}" xmlns="http://www.intuit.com/sb/cdm/v2">
+          <ExternalRealmId>#{self.realm_id}</ExternalRealmId>
+          #{xml_node}
+          </Mod>
+          XML
+          perform_write(Quickeebooks::Windows::Model::Customer, xml)
         end
 
       end

data/spec/quickeebooks/windows/services/customer_spec.rb

@@ -153,6 +153,26 @@ describe "Quickeebooks::Windows::Service::Customer" do
     create_response.success.party_role_ref.id.value.should == "6762304"
     create_response.success.request_name.should == "CustomerAdd"
   end
+  
+  it "can update a customer name" do
+    customer_xml = File.read(File.dirname(__FILE__) + "/../../../xml/windows/customer.xml")
+    update_response_xml = File.read(File.dirname(__FILE__) + "/../../../xml/windows/customer_update_success.xml")
+    service = Quickeebooks::Windows::Service::Customer.new
+    model = Quickeebooks::Windows::Model::Customer
+    customer = model.from_xml(customer_xml)
+    customer.name.should == "Wine House"
+
+    service.access_token = @oauth
+    service.realm_id = @realm_id
+    FakeWeb.register_uri(:post, service.url_for_resource(model::REST_RESOURCE), :status => ["200", "OK"], :body => update_response_xml)
+
+    # change the name
+    customer.name = "Acme Cafe"
+    update_response = service.update(customer)
+    update_response.success?.should == true
+    update_response.success.party_role_ref.id.value.should == "6762304"
+    update_response.success.request_name.should == "CustomerMod"
+  end
 
 
 end

data/spec/xml/windows/customer_update_success.xml

@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+<RestResponse xmlns="http://www.intuit.com/sb/cdm/v2">
+	<Success RequestId="1b405391016149c593c005e45700dd01">
+		<PartyRoleRef>
+			<Id idDomain="NG">6762304</Id>
+			<SyncToken>7</SyncToken>
+			<LastUpdatedTime>2012-11-29T01:01:47Z</LastUpdatedTime>
+			<PartyReferenceId idDomain="NG">6170150</PartyReferenceId>
+		</PartyRoleRef>
+		<RequestName>CustomerMod</RequestName>
+		<ProcessedTime>2012-11-29T01:01:47Z</ProcessedTime>
+	</Success>
+</RestResponse>

data/tmp/create_customer_windows.rb

@@ -3,6 +3,7 @@ require 'oauth'
 $: << File.expand_path('./lib')
 require 'quickeebooks'
 
+# attached to "Vinosmith.qbw" in Quickbooks Simple Start 2010
 consumer_key = 'qyprdL8NUDMYcCzwp8ea9KbIhaMSRk'
 consumer_secret = 'FcE5kihBYMVQGvX9UNYMxsrM8mP7bfuxc36PLhJB'
 qb_oauth_consumer = OAuth::Consumer.new(consumer_key, consumer_secret, {
@@ -22,6 +23,22 @@ service = Quickeebooks::Windows::Service::Customer.new
 service.access_token = oauth
 service.realm_id = realm_id
 
+customer = service.fetch_by_id(1)
+puts customer.name
+if customer.notes
+  customer.notes.each { |note| puts note.content }
+end
+# UPDATE it
+customer.name = "Cody 22 TEST"
+
+customer.meta_data = nil
+customer.external_key = nil
+
+response = service.update(customer)
+#puts response.inspect
+
+#puts service.list
+=begin
 customer = Quickeebooks::Windows::Model::Customer.new
 customer.type_of = "Person"
 customer.name = "Cody Test-#{Time.now.to_i}"
@@ -38,4 +55,5 @@ billing_address.postal_code = "94117"
 billing_address.country = "USA"
 customer.address = billing_address
 result = service.create(customer)
-puts result.inspect
+puts result.inspect
+=end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quickeebooks
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-20 00:00:00.000000000 Z
+date: 2012-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: roxml
@@ -325,6 +325,7 @@ files:
 - spec/xml/windows/company_meta_data.xml
 - spec/xml/windows/customer.xml
 - spec/xml/windows/customer_create_success.xml
+- spec/xml/windows/customer_update_success.xml
 - spec/xml/windows/customers.xml
 - spec/xml/windows/fetch_customer_by_id.xml
 - spec/xml/windows/http_401.xml