basecrm 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8112801481b6cff60fccc01b1218206447b30b35
-  data.tar.gz: b30ccfcdbfe04ea0a5b518c83e77d3d9c4631827
+  metadata.gz: 9b39240e639171c284af2016c897affee25c599f
+  data.tar.gz: 4b67891d5ff434ee7e0394fca959b6e06d2d70b0
 SHA512:
-  metadata.gz: 492f991f87a6d464938ba7f1ab986571283103afa40a3fc6ee6e9a4d0475c7783a172193d09df6e9ad7f87c6c428a95103a08947d333247422749c5974a4305f
-  data.tar.gz: aaba445b34861708afebec9697d8eab35160f55b2ffe2f0ac34086ca682858e4c7ee1cb685cc8a9b46fe37a5ae0c397753c55d5dd85a93d07aa7fef0b921da7a
+  metadata.gz: 339f88a6b215e7c3c717d3200c6fa753dfdba54aba7418c72cf9dc5d69893fd4b004ac456ca97d1c3e4f5aa947556a5965cc81fe59c21d3eb87176b57355d0a7
+  data.tar.gz: a535ff335c8c6972c0a0f369e358cd90bcbd257b23003bc7033aea5b553a53a579dd6eb069310e38bc4587faeb60aed0ebd34a662af7e5956f4c8b5edaa87dec

data/README.md

@@ -9,7 +9,7 @@ Make sure you have [rubygems](https://rubygems.org) installed.
 The gem is available via Rubygems. To install, use the following command:
 
 ```ruby
-sudo gem install basecrm
+gem install basecrm
 ```
 
 If you use Bundler, put the line below in your Gemfile:
@@ -75,7 +75,7 @@ client.deals.all.map { |deal| deal.name } # => Array<String>
 To retrieve list of resources and use filtering you will call `#where` method:
 
 ```ruby
-client = BaseCRM::Client.new(accss_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.deals.where(organization_id: google.id, hot: true) # => Array<BaseCRM::Deal>
 ```
 
@@ -102,7 +102,7 @@ client.deals.update(deal) # => BaseCRM::Deal
 To destroy a resource use `#destroy` method:
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOU_PERSONAL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.deals.destroy(id) # => true
 ```
 
@@ -120,6 +120,28 @@ lead.website = "http://www.designservices.com"
 client.leads.update(lead)
 ```
 
+## Sync API
+
+The following sample code shows how to perform a full synchronization flow using high-level wrapper.
+
+First of all you need an instance of `BaseCRM::Client`. High-level `BaseCRM::Sync` wrapper is using `BaseCRM::SyncService` to interact with the Sync API.
+In addition to the client instance, you must provide a device’s UUID within `device_uuid` parameter. The device’s UUID must not change between synchronization sessions, otherwise the sync service will not recognize the device and will send all the data again.
+
+```ruby
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
+sync = BaseCRM::Sync.new(client: client, device_uuid: "<YOUR_DEVICES_UUID>")
+```
+
+Now all you have to do is to call `#fetch` method and pass a block that you might use to store fetched data to a database.
+
+```ruby
+sync.fetch do |sync_meta, resource|
+  DB.send(sync_meta.event_type, resource) ? sync_meta.ack : sync_meta.nack
+end
+```
+
+Notice that you must call either `#ack` or `#nack` method.
+
 ## Resources and actions
 
 Documentation for every action can be found in corresponding service files under `lib/basecrm/services` directory.
@@ -127,7 +149,7 @@ Documentation for every action can be found in corresponding service files under
 ### Account
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.accounts # => BaseCRM::AccountsService
 ```
 
@@ -137,7 +159,7 @@ Actions:
 ### AssociatedContact
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.associated_contacts # => BaseCRM::AssociatedContactsService
 ```
 
@@ -149,7 +171,7 @@ Actions:
 ### Contact
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.contacts # => BaseCRM::ContactsService
 ```
 
@@ -163,7 +185,7 @@ Actions:
 ### Deal
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.deals # => BaseCRM::DealsService
 ```
 
@@ -177,7 +199,7 @@ Actions:
 ### Lead
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.leads # => BaseCRM::LeadsService
 ```
 
@@ -191,7 +213,7 @@ Actions:
 ### LossReason
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.loss_reasons # => BaseCRM::LossReasonsService
 ```
 
@@ -205,7 +227,7 @@ Actions:
 ### Note
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.notes # => BaseCRM::NotesService
 ```
 
@@ -219,7 +241,7 @@ Actions:
 ### Pipeline
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.pipelines # => BaseCRM::PipelinesService
 ```
 
@@ -229,7 +251,7 @@ Actions:
 ### Source
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.sources # => BaseCRM::SourcesService
 ```
 
@@ -243,7 +265,7 @@ Actions:
 ### Stage
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.stages # => BaseCRM::StagesService
 ```
 
@@ -253,7 +275,7 @@ Actions:
 ### Tag
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.tags # => BaseCRM::TagsService
 ```
 
@@ -267,7 +289,7 @@ Actions:
 ### Task
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.tasks # => BaseCRM::TasksService
 ```
 
@@ -281,7 +303,7 @@ Actions:
 ### User
 
 ```ruby
-client = BaseCRM::Client.new(access_token: "<YOUR_PERSONL_ACCESS_TOKEN>")
+client = BaseCRM::Client.new(access_token: "<YOUR_PERSONAL_ACCESS_TOKEN>")
 client.users # => BaseCRM::UsersService
 ```
 

data/lib/basecrm.rb

@@ -22,6 +22,9 @@ require 'basecrm/models/stage'
 require 'basecrm/models/tag'
 require 'basecrm/models/task'
 require 'basecrm/models/user'
+require 'basecrm/models/sync_queue'
+require 'basecrm/models/sync_session'
+require 'basecrm/models/sync_meta'
 
 require 'basecrm/paginated_resource'
 require 'basecrm/services/accounts_service'
@@ -37,6 +40,9 @@ require 'basecrm/services/stages_service'
 require 'basecrm/services/tags_service'
 require 'basecrm/services/tasks_service'
 require 'basecrm/services/users_service'
+require 'basecrm/services/sync_service'
+
+require 'basecrm/sync'
 
 module BaseCRM
   class Client
@@ -66,121 +72,129 @@ module BaseCRM
       @http_client = HttpClient.new(@config)
     end
 
-    # Access all Accounts related actions. 
-    # @see AccountsService 
+    # Access all Accounts related actions.
+    # @see AccountsService
     # @see Account
-    # 
+    #
     # @return [AccountsService] Service object for  resources.
     def accounts
       @accounts ||= AccountsService.new(@http_client)
     end
 
-    # Access all AssociatedContacts related actions. 
-    # @see AssociatedContactsService 
+    # Access all AssociatedContacts related actions.
+    # @see AssociatedContactsService
     # @see AssociatedContact
-    # 
+    #
     # @return [AssociatedContactsService] Service object for  resources.
     def associated_contacts
       @associated_contacts ||= AssociatedContactsService.new(@http_client)
     end
 
-    # Access all Contacts related actions. 
-    # @see ContactsService 
+    # Access all Contacts related actions.
+    # @see ContactsService
     # @see Contact
-    # 
+    #
     # @return [ContactsService] Service object for  resources.
     def contacts
       @contacts ||= ContactsService.new(@http_client)
     end
 
-    # Access all Deals related actions. 
-    # @see DealsService 
+    # Access all Deals related actions.
+    # @see DealsService
     # @see Deal
-    # 
+    #
     # @return [DealsService] Service object for  resources.
     def deals
       @deals ||= DealsService.new(@http_client)
     end
 
-    # Access all Leads related actions. 
-    # @see LeadsService 
+    # Access all Leads related actions.
+    # @see LeadsService
     # @see Lead
-    # 
+    #
     # @return [LeadsService] Service object for  resources.
     def leads
       @leads ||= LeadsService.new(@http_client)
     end
 
-    # Access all LossReasons related actions. 
-    # @see LossReasonsService 
+    # Access all LossReasons related actions.
+    # @see LossReasonsService
     # @see LossReason
-    # 
+    #
     # @return [LossReasonsService] Service object for  resources.
     def loss_reasons
       @loss_reasons ||= LossReasonsService.new(@http_client)
     end
 
-    # Access all Notes related actions. 
-    # @see NotesService 
+    # Access all Notes related actions.
+    # @see NotesService
     # @see Note
-    # 
+    #
     # @return [NotesService] Service object for  resources.
     def notes
       @notes ||= NotesService.new(@http_client)
     end
 
-    # Access all Pipelines related actions. 
-    # @see PipelinesService 
+    # Access all Pipelines related actions.
+    # @see PipelinesService
     # @see Pipeline
-    # 
+    #
     # @return [PipelinesService] Service object for  resources.
     def pipelines
       @pipelines ||= PipelinesService.new(@http_client)
     end
 
-    # Access all Sources related actions. 
-    # @see SourcesService 
+    # Access all Sources related actions.
+    # @see SourcesService
     # @see Source
-    # 
+    #
     # @return [SourcesService] Service object for  resources.
     def sources
       @sources ||= SourcesService.new(@http_client)
     end
 
-    # Access all Stages related actions. 
-    # @see StagesService 
+    # Access all Stages related actions.
+    # @see StagesService
     # @see Stage
-    # 
+    #
     # @return [StagesService] Service object for  resources.
     def stages
       @stages ||= StagesService.new(@http_client)
     end
 
-    # Access all Tags related actions. 
-    # @see TagsService 
+    # Access all Tags related actions.
+    # @see TagsService
     # @see Tag
-    # 
+    #
     # @return [TagsService] Service object for  resources.
     def tags
       @tags ||= TagsService.new(@http_client)
     end
 
-    # Access all Tasks related actions. 
-    # @see TasksService 
+    # Access all Tasks related actions.
+    # @see TasksService
     # @see Task
-    # 
+    #
     # @return [TasksService] Service object for  resources.
     def tasks
       @tasks ||= TasksService.new(@http_client)
     end
 
-    # Access all Users related actions. 
-    # @see UsersService 
+    # Access all Users related actions.
+    # @see UsersService
     # @see User
-    # 
+    #
     # @return [UsersService] Service object for  resources.
     def users
       @users ||= UsersService.new(@http_client)
     end
+
+    # Access Sync API related low-level actions.
+    # @see SyncService
+    #
+    # @return [SyncService] Service object for Sync API.
+    def sync
+      @sync ||= SyncService.new(@http_client)
+    end
   end
 end

data/lib/basecrm/http_client.rb

@@ -30,25 +30,25 @@ module BaseCRM
       end
     end
 
-    def get(path, params={})
-      request(:get, path, params)
+    def get(path, params={}, headers={})
+      request(:get, path, params, headers)
     end
 
-    def post(path, body={})
-      request(:post, path, body)
+    def post(path, body={}, headers={})
+      request(:post, path, body, headers)
     end
 
-    def put(path, body={})
-      request(:put, path, body)
+    def put(path, body={}, headers={})
+      request(:put, path, body, headers)
     end
 
-    def delete(path, params={})
+    def delete(path, params={}, headers={})
       request(:delete, path, params)
     end
 
-    def request(method, path, data={})
+    def request(method, path, data={}, headers={})
       options = {
-        headers: @headers
+        headers: @headers.merge(headers.to_h)
       }
 
       case method.to_s.downcase.to_sym

data/lib/basecrm/models/sync_meta.rb

@@ -0,0 +1,29 @@
+module BaseCRM
+  class SyncMeta < Model
+    # @attribute [r] event_type
+    #   @return [String] An event type. Possible values: `created`, `updated`, `deleted`.
+    # attr_reader :event_type
+
+    # @attribute [r] ack_key
+    #   @return [String] An acknowledgement key.
+    # attr_reader :ack_key
+
+    # @attribute [r] revision
+    #   @return [String] Data revision.
+    # attr_reader :revision
+
+    def acknowledged?
+      !!@acknowledged
+    end
+
+    def ack
+      @acknowledged = true
+      [:ack, self.ack_key]
+    end
+
+    def nack
+      @acknowledged = true
+      [:nack, self.ack_key]
+    end
+  end
+end

data/lib/basecrm/models/sync_queue.rb

@@ -0,0 +1,15 @@
+module BaseCRM
+  class SyncQueue < Model
+    # @attribute [r] name
+    #   @return [String] Name of the queue.
+    # attr_reader :name
+
+    # @attribute [r] pages
+    #   @return [Integer] Number of pages to request.
+    # attr_reader :pages
+
+    # @attribute [r] total_count
+    #   @return [Integer] Total number of items in the queue to synchronize.
+    # attr_reader :total_count
+  end
+end

data/lib/basecrm/models/sync_session.rb

@@ -0,0 +1,11 @@
+module BaseCRM
+  class SyncSession < Model
+    # @attribute [r] id
+    #   @return [String] Unique identifier for the sync session.
+    # attr_reader :id
+
+    # @attribute [r] queues
+    #   @return [Array<SyncQueue>] A list of sync queues.
+    # attr_reader :queues
+  end
+end

data/lib/basecrm/services/sync_service.rb

@@ -0,0 +1,94 @@
+module BaseCRM
+  class SyncService
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Start synchronization flow
+    #
+    # post '/sync/start'
+    #
+    # Starts a new synchronization session.
+    # This is the first endpoint to call, in order to start a new synchronization session.
+    #
+    # @param device_uuid [String] Device's UUID for which to perform synchronization.
+    # @return [SyncSession] The resulting object is the synchronization session object or nil if there is nothing to synchronize.
+    def start(device_uuid)
+      validate_device!(device_uuid)
+
+      status, _, root = @client.post("/sync/start", {}, build_headers(device_uuid))
+      return nil if status == 204
+
+      build_session(root)
+    end
+
+    # Get data from queue
+    #
+    # get '/sync/{session_id}/queues/main'
+    #
+    # Fetch fresh data from the main queue.
+    # Using session identifier you call continously the `#fetch` method to drain the main queue.
+    #
+    # @param device_uuid [String] Device's UUID for which to perform synchronization
+    # @param session_id [String] Unique identifier of a synchronization session.
+    # @param queue [String|Symbol] Queue name.
+    # @return [Array<Array<SyncMeta, Model>>] The list of sync's metadata associated with data and data.
+    def fetch(device_uuid, session_id, queue='main')
+      validate_device!(device_uuid)
+      raise ArgumentError, "session_id must not be nil nor empty" unless session_id && !session_id.strip.empty?
+      raise ArgumentError, "queue name must not be nil nor empty" unless queue && !queue.strip.empty?
+
+      status, _, root = @client.get("/sync/#{session_id}/queues/#{queue}", {}, build_headers(device_uuid))
+      return [] if status == 204
+
+      root[:items].map do |item|
+        klass = classify_type(item[:meta][:type])
+        [SyncMeta.new(item[:meta][:sync]), klass.new(item[:data])]
+      end
+    end
+
+    # Acknowledge received data
+    #
+    # post '/sync/ack'
+    #
+    # Send acknowledgement keys to let know the Sync service which data you have.
+    # As you fetch new data, you need to send acknowledgement keys.
+    #
+    # @param device_uuid [String] Device's UUID for which to perform synchronization.
+    # @param ack_keys [Array<String>] The list of acknowledgement keys.
+    # @return [Boolean] Status of the operation.
+    def ack(device_uuid, ack_keys)
+      validate_device!(device_uuid)
+      raise ArgumentError, "ack_keys must not be nil and an array" unless ack_keys && ack_keys.is_a?(Array)
+      return true if ack_keys.empty?
+
+      payload = {
+        :ack_keys => ack_keys.map(&:to_s)
+      }
+      status, _, _ = @client.post('/sync/ack', payload, build_headers(device_uuid))
+      status == 202
+    end
+
+  private
+    def validate_device!(device_uuid)
+      raise ArgumentError, "device_uuid must not be nil nor empty" unless device_uuid && !device_uuid.strip.empty?
+    end
+
+    def build_headers(device_uuid)
+      {
+        "X-Basecrm-Device-UUID" => device_uuid
+      }
+    end
+
+    def classify_type(type)
+      BaseCRM.const_get(type.split('_').map(&:capitalize).join)
+    end
+
+    def build_session(root)
+      session_data = root[:data]
+      session_data[:queues] = session_data[:queues].map { |queue| SyncQueue.new(queue[:data]) }
+      SyncSession.new(session_data)
+    end
+  end
+end

data/lib/basecrm/sync.rb

@@ -0,0 +1,82 @@
+module BaseCRM
+  class Sync
+    attr_reader :device_uuid
+    attr_reader :client
+
+    # Intantiate a new BaseCRM Sync API V2 high-level wrapper
+    #
+    # @param options[Hash] Wrapper options
+    # @option options [String] :device_uuid Device's UUID.
+    # @option options [BaseCRM::Client] :client BaseCRM API v2 client instance.
+    #
+    # @raise [ConfigurationError] if no device's uuid provided
+    # @raise [ConfigurationError] if no client instance provided
+    #
+    # @return [Sync] New wrapper instance
+    #
+    # @see Client
+    # @see SyncService
+    def initialize(options)
+      @device_uuid = options[:device_uuid]
+      @client = options[:client]
+
+      validate!
+    end
+
+    # Perform a full synchronization flow.
+    # See the following example:
+    #
+    #   client = BaseCRM::Client.new(access_token: "<YOUR_ACCESS_TOKEN>")
+    #   sync = BaseCRM::Sync.new(client: client, device_uuid: "<YOUR_DEVICES_UUID>")
+    #   sync.fetch do |sync_meta, resource|
+    #     DB.send(sync_meta.event_type, entity) ? sync_meta.ack : sync_meta.nack
+    #   end
+    #
+    # @param block [Proc] Procedure that will be called for every item in the queue. Takes two input arguments: SyncMeta instance
+    #   associated with the resource, and the resource. You should use either `SyncQueue#ack` or `SyncQueue#nack` to return value from the block.
+    #
+    # @return nil
+    def fetch(&block)
+      return unless block_given?
+
+      # Set up a new synchronization session for given device's UUID
+      session = @client.sync.start(@device_uuid)
+
+      # Check if there is anything to synchronize
+      return unless  session && session.id
+
+      # Drain the main queue unitl there is no more data (empty array)
+      loop do
+        queued_data = @client.sync.fetch(@device_uuid, session.id)
+
+        # nothing more to synchronize ?
+        break if queued_data.empty?
+
+        ack_keys = []
+        queued_data.each do |sync_meta, resource|
+          op, ack_key = block.call(sync_meta, resource)
+          ack_keys << ack_key if op == :ack
+        end
+
+        # As we fetch new data, we need to send ackwledgement keys - if any
+        @client.sync.ack(@device_uuid, ack_keys) unless ack_keys.empty?
+      end
+    end
+
+  private
+    def validate!
+      unless @device_uuid
+        raise ConfigurationError.new('No device UUID provided. '\
+          'The UUID must not change between synchronization sessions. '\
+          'Set your device\'s UUID during wrapper initialization using: '\
+          '"Base::Sync.new(device_uuid: <YOUR_DEVICES_UUID>, client: client)".')
+      end
+
+      unless @client
+        raise ConfigurationError.new('No "BaseCRM::Client" instance provided. '\
+          'The high-level sync wrapper is using "BaseCRM::SyncService"\'s lowl-level interface '\
+          'exposed within "BaseCRM::Client" scope.')
+      end
+    end
+  end
+end

data/lib/basecrm/version.rb

@@ -1,3 +1,3 @@
 module BaseCRM
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/spec/basecrm/sync_spec.rb

@@ -0,0 +1,94 @@
+require 'spec_helper'
+
+describe BaseCRM::Sync do
+  let(:device_uuid) { '6dadcec8-6e61-4691-b318-1aab27b8fecf' }
+  let(:session_id) { '29f2aeeb-8d68-4ea7-95c3-a2c8e151f5a3' }
+
+  subject { BaseCRM::Sync.new(device_uuid: device_uuid, client: client) }
+
+  describe 'Responds to' do
+    it { should respond_to :fetch }
+  end
+
+  describe :initialize do
+    describe 'validation' do
+      context 'no device_uuid option' do
+        it 'raises BaseCRM::ConfigurationError exception' do
+          expect { BaseCRM::Sync.new(client: client) }.to raise_error BaseCRM::ConfigurationError
+        end
+      end
+
+      context 'no client option' do
+        it 'raises BaseCRM::ConfigurationError exception' do
+          expect { BaseCRM::Sync.new(device_uuid: device_uuid) }.to raise_error BaseCRM::ConfigurationError
+        end
+      end
+
+      context 'required options passed' do
+        it 'raises no exception' do
+          expect { BaseCRM::Sync.new(client: client, device_uuid: device_uuid) }.not_to raise_error
+        end
+      end
+    end
+  end
+
+  describe :fetch do
+    context 'no block passed' do
+      it 'does nothing' do
+        expect(client).not_to receive(:sync)
+        subject.fetch
+      end
+    end
+
+    context 'nothing to synchronize' do
+      before :each do
+        expect(client.sync).to receive(:start).with(device_uuid).and_return(nil)
+      end
+
+      it 'returns early' do
+        expect(subject.fetch { |s, r| :nop }).to be_nil
+      end
+    end
+
+    context 'fresh data to synchronize' do
+      let(:session) do
+        BaseCRM::SyncSession.new(id: session_id)
+      end
+
+      let(:ack_keys) do
+        ['User-1234-1', 'Source-1234-1']
+      end
+
+      let(:queue_items) do
+        [
+          [BaseCRM::SyncMeta.new(event_type: 'created', ack_key: 'User-1234-1'), BaseCRM::User.new(id: 1)],
+          [BaseCRM::SyncMeta.new(event_type: 'created', ack_key: 'Source-1234-1'), BaseCRM::Source.new(id: 1)]
+        ]
+      end
+
+      before :each do
+        expect(client.sync).to receive(:start).with(device_uuid).and_return(session)
+        expect(client.sync).to receive(:fetch).with(device_uuid, session_id).and_return(queue_items)
+        expect(client.sync).to receive(:fetch).with(device_uuid, session_id).and_return([])
+        expect(client.sync).to receive(:ack).with(device_uuid, ack_keys).and_return(true)
+      end
+
+      it 'does whole synchronization flow' do
+        subject.fetch { |s, r| s.ack }
+      end
+
+      it 'calls a provided block as many times as items in the queue' do
+        counter = 0
+        subject.fetch { |s, r| counter += 1; s.ack }
+        expect(counter).to eq(2)
+      end
+
+      it 'passes two elements to provided block: first element is BaseCRM::SyncMeta and the second is a resource' do
+        subject.fetch do |s, r|
+          expect(s).to be_a BaseCRM::SyncMeta
+          s.ack
+        end
+      end
+    end
+  end
+end

data/spec/models/sync_meta_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+
+describe BaseCRM::SyncMeta do
+  describe 'Responds to' do
+    it { should respond_to :ack }
+    it { should respond_to :nack }
+    it { should respond_to :acknowledged? }
+  end
+
+  describe :ack do
+    subject { BaseCRM::SyncMeta }
+
+    it 'returns array' do
+      expect(subject.new.ack).to be_an Array
+    end
+
+    it 'returns two elements array' do
+      expect(subject.new(ack_key: "123").ack).to eq([:ack, "123"])
+    end
+  end
+
+  describe :nack do
+    subject { BaseCRM::SyncMeta }
+
+    it 'returns array' do
+      expect(subject.new.nack).to be_an Array
+    end
+
+    it 'returns two elements array' do
+      expect(subject.new(ack_key: "123").nack).to eq([:nack, "123"])
+    end
+  end
+
+  describe :acknowledged? do
+    subject { BaseCRM::SyncMeta }
+
+    context 'neither ack nor nack method called' do
+      it 'return false value' do
+        expect(subject.new.acknowledged?).to eq(false)
+      end
+    end
+
+    context 'ack method called' do
+      it 'return true value' do
+        ack_meta = subject.new
+        ack_meta.ack
+        expect(ack_meta.acknowledged?).to eq(true)
+      end
+    end
+
+    context 'nack method called' do
+      it 'return true value' do
+        ack_meta = subject.new
+        ack_meta.nack
+        expect(ack_meta.acknowledged?).to eq(true)
+      end
+    end
+  end
+end

data/spec/services/sync_service_spec.rb

@@ -0,0 +1,283 @@
+require 'spec_helper'
+
+describe BaseCRM::SyncService do
+  let(:device_uuid) { '6dadcec8-6e61-4691-b318-1aab27b8fecf' }
+  let(:session_id) { '29f2aeeb-8d68-4ea7-95c3-a2c8e151f5a3' }
+
+  describe 'Responds to' do
+    subject { BaseCRM::SyncService.new(double) }
+
+    it { should respond_to :start }
+    it { should respond_to :ack }
+    it { should respond_to :fetch }
+  end
+
+  describe 'Client respond to' do
+    subject { client }
+
+    it { should respond_to :sync }
+  end
+
+  describe 'Client#sync' do
+    it 'returns BaseCRM::SyncService instance' do
+      expect(client.sync).to be_a BaseCRM::SyncService
+    end
+  end
+
+  describe :start do
+    describe 'validation' do
+      context 'device_uuid is nil' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.start(nil) }.to raise_error(ArgumentError)
+        end
+      end
+
+      context 'device_uuid is empty' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.start(" ") }.to raise_error(ArgumentError)
+        end
+      end
+    end
+
+    context 'nothing new to fetch' do
+      let(:http_response) do
+        [204, {}, nil]
+      end
+
+      it 'returns nil' do
+        expect(client.http_client).to receive(:post).with('/sync/start', {}, {'X-Basecrm-Device-UUID' => device_uuid}).and_return(http_response)
+        expect(client.sync.start(device_uuid)).to be_nil
+      end
+    end
+
+    context 'we have to data to synchronize' do
+      let(:payload) do
+        {
+          data: {
+            id: session_id,
+            queues: [
+              data: {
+                name: 'main',
+                pages: 1,
+                total_count: 2
+              },
+              meta: {
+                type: :sync_queue
+              }
+            ]
+          },
+          meta: {
+            type: :sync_session
+          }
+        }
+      end
+
+      let(:http_response) do
+        [201, {}, payload]
+      end
+
+      before :each do
+        expect(client.http_client).to receive(:post).with('/sync/start', {}, {'X-Basecrm-Device-UUID' => device_uuid}).and_return(http_response)
+      end
+
+      it 'returns an instance of BaseCRM::SyncSession' do
+        expect(client.sync.start(device_uuid)).to be_an BaseCRM::SyncSession
+      end
+
+      it "flattens BaseCRM::SyncSession's queues" do
+        client.sync.start(device_uuid).queues.each do |queue|
+          expect(queue).to be_an BaseCRM::SyncQueue
+        end
+      end
+    end
+  end
+
+  describe :ack do
+    let(:http_response) do
+      [202, {}, nil]
+    end
+
+    let(:ack_keys) do
+      ['User-1234-1', 'Source-1234-1']
+    end
+
+    describe 'validation' do
+      context 'device_uuid is nil' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.ack(nil, ack_keys) }.to raise_error(ArgumentError)
+        end
+      end
+
+      context 'device_uuid is empty' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.ack(" ", ack_keys) }.to raise_error(ArgumentError)
+        end
+      end
+
+      context 'ack_keys is nil' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.ack(device_uuid, nil) }.to raise_error(ArgumentError)
+        end
+      end
+
+      context 'ack_keys is not an Array' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.ack(device_uuid, {}) }.to raise_error(ArgumentError)
+        end
+      end
+    end
+
+    context 'empty ack_keys array' do
+      let(:ack_keys) do
+        []
+      end
+
+      it 'returns imedieatly with true value' do
+        expect(client.http_client).not_to receive(:post)
+        expect(client.sync.ack(device_uuid, ack_keys)).to eq(true)
+      end
+    end
+
+    context 'non empty ack_keys call' do
+      it 'returns true value' do
+        expect(client.http_client).to receive(:post).with('/sync/ack', {ack_keys: ack_keys}, {'X-Basecrm-Device-UUID' => device_uuid}).and_return(http_response)
+        expect(client.sync.ack(device_uuid, ack_keys)).to eq(true)
+      end
+    end
+  end
+
+  describe :fetch do
+    context 'validation' do
+      context 'device_uuid is nil' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.fetch(nil, session_id) }.to raise_error(ArgumentError)
+        end
+      end
+
+      context 'device_uuid is empty' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.fetch(" ", session_id) }.to raise_error(ArgumentError)
+        end
+      end
+
+      context 'session_id is nil' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.fetch(device_uuid, nil) }.to raise_error(ArgumentError)
+        end
+      end
+
+      context 'session_id is empty' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.fetch(device_uuid, ' ') }.to raise_error(ArgumentError)
+        end
+      end
+
+      context 'queue names is nil' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.fetch(device_uuid, session_id, nil) }.to raise_error(ArgumentError)
+        end
+      end
+
+      context 'queue names is empty' do
+        it 'raises ArgumentError exception' do
+          expect { client.sync.fetch(device_uuid, session_id, ' ') }.to raise_error(ArgumentError)
+        end
+      end
+    end
+
+    context 'no more data to fetch' do
+      let(:http_response) do
+        [204, {}, nil]
+      end
+
+      it 'returns an empty array' do
+        expect(client.http_client).to receive(:get).with("/sync/#{session_id}/queues/main", {}, {'X-Basecrm-Device-UUID' => device_uuid}).and_return(http_response)
+        expect(client.sync.fetch(device_uuid, session_id)).to eq([])
+      end
+    end
+
+    context 'there is still data in the main queue' do
+      let(:payload) do
+        {
+          items: [
+            {
+              data: {
+                id: 1
+              },
+              meta: {
+                type: 'user',
+                sync: {
+                  event_type: 'created',
+                  ack_key: 'User-123-1',
+                  revision: 1
+                }
+              }
+            },
+            {
+              data: {
+                id: 1
+              },
+              meta: {
+                type: 'source',
+                sync: {
+                  event_type: 'created',
+                  ack_key: 'Source-123-1',
+                  revision: 1
+                }
+              }
+            }
+          ],
+          meta: {
+            type: 'collection',
+            count: 2,
+            count_left: 0
+          }
+        }
+      end
+
+      let(:http_response) do
+        [200, {}, payload]
+      end
+
+      before :each do
+        expect(client.http_client).to receive(:get).with("/sync/#{session_id}/queues/main", {}, {'X-Basecrm-Device-UUID' => device_uuid}).and_return(http_response)
+      end
+
+      it 'returns an array' do
+        expect(client.sync.fetch(device_uuid, session_id)).to be_an Array
+      end
+
+      it 'returns a non empty array' do
+        expect(client.sync.fetch(device_uuid, session_id)).not_to be_empty
+      end
+
+      it 'returns an array of two items' do
+        expect(client.sync.fetch(device_uuid, session_id).length).to eq(2)
+      end
+
+      it 'returns an array of arrays' do
+        client.sync.fetch(device_uuid, session_id).each do |item|
+          expect(item).to be_an Array
+          expect(item).not_to be_empty
+          expect(item.length).to eq(2)
+        end
+      end
+
+      it 'returns an array where the first element is BaseCRM::SyncMeta and the second is a model' do
+        items = client.sync.fetch(device_uuid, session_id)
+
+        sync_meta, user = items[0]
+        expect(sync_meta).to be_a BaseCRM::SyncMeta
+        expect(user).to be_a BaseCRM::User
+        expect(sync_meta.ack_key).to eq('User-123-1')
+        expect(user.id).to eq(1)
+
+        sync_meta, source = items[1]
+        expect(sync_meta).to be_a BaseCRM::SyncMeta
+        expect(source).to be_a BaseCRM::Source
+        expect(sync_meta.ack_key).to eq('Source-123-1')
+        expect(source.id).to eq(1)
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecrm
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - BaseCRM developers
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-04-17 00:00:00.000000000 Z
+date: 2015-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -148,6 +148,9 @@ files:
 - lib/basecrm/models/pipeline.rb
 - lib/basecrm/models/source.rb
 - lib/basecrm/models/stage.rb
+- lib/basecrm/models/sync_meta.rb
+- lib/basecrm/models/sync_queue.rb
+- lib/basecrm/models/sync_session.rb
 - lib/basecrm/models/tag.rb
 - lib/basecrm/models/task.rb
 - lib/basecrm/models/user.rb
@@ -162,10 +165,13 @@ files:
 - lib/basecrm/services/pipelines_service.rb
 - lib/basecrm/services/sources_service.rb
 - lib/basecrm/services/stages_service.rb
+- lib/basecrm/services/sync_service.rb
 - lib/basecrm/services/tags_service.rb
 - lib/basecrm/services/tasks_service.rb
 - lib/basecrm/services/users_service.rb
+- lib/basecrm/sync.rb
 - lib/basecrm/version.rb
+- spec/basecrm/sync_spec.rb
 - spec/factories/associated_contact.rb
 - spec/factories/contact.rb
 - spec/factories/deal.rb
@@ -175,6 +181,7 @@ files:
 - spec/factories/source.rb
 - spec/factories/tag.rb
 - spec/factories/task.rb
+- spec/models/sync_meta_spec.rb
 - spec/services/accounts_service_spec.rb
 - spec/services/associated_contacts_service_spec.rb
 - spec/services/contacts_service_spec.rb
@@ -185,6 +192,7 @@ files:
 - spec/services/pipelines_service_spec.rb
 - spec/services/sources_service_spec.rb
 - spec/services/stages_service_spec.rb
+- spec/services/sync_service_spec.rb
 - spec/services/tags_service_spec.rb
 - spec/services/tasks_service_spec.rb
 - spec/services/users_service_spec.rb
@@ -210,11 +218,12 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.3
 signing_key: 
 specification_version: 4
 summary: BaseCRM Official API V2 library client for ruby
 test_files:
+- spec/basecrm/sync_spec.rb
 - spec/factories/associated_contact.rb
 - spec/factories/contact.rb
 - spec/factories/deal.rb
@@ -224,6 +233,7 @@ test_files:
 - spec/factories/source.rb
 - spec/factories/tag.rb
 - spec/factories/task.rb
+- spec/models/sync_meta_spec.rb
 - spec/services/accounts_service_spec.rb
 - spec/services/associated_contacts_service_spec.rb
 - spec/services/contacts_service_spec.rb
@@ -234,6 +244,7 @@ test_files:
 - spec/services/pipelines_service_spec.rb
 - spec/services/sources_service_spec.rb
 - spec/services/stages_service_spec.rb
+- spec/services/sync_service_spec.rb
 - spec/services/tags_service_spec.rb
 - spec/services/tasks_service_spec.rb
 - spec/services/users_service_spec.rb