Sync API

.gitignore

@@ -7,4 +7,5 @@ coverage
 \.yardoc
 .DS_Store
 .bundle/
-*/rspec_results.html
+*/rspec_results.html
+vendor/

CHANGELOG.md

@@ -1,6 +1,12 @@
 ## CHANGELOG
 ------------------------------------------------
 
+## Version 0.3.0
+### Date: 17th-Mar-2021
+ ### New Features
+ - Sync API module support added
+
+ ------------------------------------------------
 ## Version 0.2.0
 
  ### New Features

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2012-2019 Contentstack. All Rights Reserved
+Copyright (c) 2012-2021 Contentstack. All Rights Reserved
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -19,7 +19,7 @@ Or you can run this command in your terminal (you might need administrator privi
     gem install contentstack
 
 To start using the SDK in your application, you will need to initialize the stack by providing the values for the keys given in the code snippet below.
-
+```ruby
     # with default region
     client = Contentstack::Client.new("api_key", "delivery_token", "enviroment_name")
 
@@ -28,6 +28,7 @@ To start using the SDK in your application, you will need to initialize the stac
 
     # with custom host
     client = Contentstack::Client.new("api_key", "delivery_token", "enviroment_name",{"host": "https://custom-cdn.contentstack.com"})
+```
 
 ## **Key Concepts for using Contentstack**
 
@@ -56,35 +57,40 @@ A publishing environment corresponds to one or more deployment servers or a cont
 ### **Initializing your SDK**
 
 To initialize the SDK, you need to provide values for the keys given in the snippet below:
-
-    stack = Contentstack::Client.new("api_key", "delivery_token", "enviroment_name")
+```ruby
+@stack = Contentstack::Client.new("api_key", "delivery_token", "enviroment_name")
+```
 
 To get the API credentials mentioned above, log in to your Contentstack account and then in your top panel navigation, go to Settings > Stack to view the API Key and Access Token.
 
 ### **Querying content from your stack**
 
 To fetch all entries of of a content type, use the query given below:
-
-    entry = stack.content_type(<<CONTENT_TYPE_UID>>).query();
+```ruby
+@entry = stack.content_type(<<CONTENT_TYPE_UID>>).query();
+```
 
 To fetch a specific entry from a content type, use the following query:
-
-    entry = stack.content_type(<<CONTENT_TYPE_UID>>).entry(<<ENTRY_UID>>);
+```ruby
+@entry = stack.content_type(<<CONTENT_TYPE_UID>>).entry(<<ENTRY_UID>>);
+```
 
 ### Get Multiple Entries
 To retrieve multiple entries of a content type, specify the content type UID. You can also specify search parameters to filter results:
+```ruby
+@query = @stack.content_type('blog').query
+@entries = @query.where('title', 'welcome')
+                .include_schema
+                .include_count
+                .fetch
+puts "Total Entries -- #{@entries.count}"
+@entries.each{|entry| puts "#{entry.get('title')}" }
+```
 
-    @query = @stack.content_type('blog').query
-    @entries = @query.where('title', 'welcome')
-                    .include_schema
-                    .include_count
-                    .fetch
-    puts "Total Entries -- #{@entries.count}"
-    @entries.each{|entry| puts "#{entry.get('title')}" }
 To retrieve localized versions of entries, you can use the query attribute:
-
-    entry = @stack.content_type('content_type_uid').query.locale('locale_code').fetch()
-
+```ruby
+entry = @stack.content_type('content_type_uid').query.locale('locale_code').fetch()
+```
 > Note: Currently, the above query works in case of retrieving localized versions of multiple entries only.
 
 ## **Advanced Queries**
@@ -96,11 +102,13 @@ You can query for content types, entries, assets and more using our Ruby API Ref
 ### Paginating Responses
 In a single instance, the [Get Multiple Entries](https://www.contentstack.com/docs/developers/ruby/get-started-with-ruby-sdk/#get-multiple-entries) query will retrieve only the first 100 items of the specified content type. You can paginate and retrieve the rest of the items in batches using the [skip](https://www.rubydoc.info/gems/contentstack/Contentstack/Query#skip-instance_method) and [limit](https://www.rubydoc.info/gems/contentstack/Contentstack/Query#limit-instance_method) parameters in subsequent requests.
 
-    @stack = Contentstack::Client.new("api_key", "delivery_token", "environment")
-    @entries = @stack.content_type('category').query
-                   .limit(20)
-                   .skip(50)
-                   .fetch
+```ruby
+@stack = Contentstack::Client.new("api_key", "delivery_token", "environment")
+@entries = @stack.content_type('category').query
+                .limit(20)
+                .skip(50)
+                .fetch
+```
 
 > Note: Currently, the Ruby SDK does not support multiple content types referencing in a single query. For more information on how to query entries and assets, refer the Queries section of our Content Delivery API documentation.
 
@@ -112,8 +120,63 @@ For example, if you want to crop an image (with width as 300 and height as 400),
 
 [Read Image Delivery API documentation](https://www.contentstack.com/docs/apis/image-delivery-api/). 
 
-SDK functions for Image Delivery API coming soon. 
 
+## **Using the Sync API with Ruby SDK**
+
+The Sync API takes care of syncing your Contentstack data with your app and ensures that the data is always up-to-date by providing delta updates. Contentstack’s Ruby SDK supports Sync API, which you can use to build powerful apps. Read through to understand how to use the Sync API with Contentstack Ruby SDK.
+[Read Sync API documentation](https://www.contentstack.com/docs/platforms/ruby#using-the-sync-api-with-ruby-sdk).
+
+### Initial sync
+
+The Initial Sync process performs a complete sync of your app data. It returns all the published entries and assets of the specified stack in response.
+
+To start the Initial Sync process, use the syncStack method.
+
+```ruby
+@sync_result = @stack.sync({init: true})
+# @sync_result.items: contains sync data
+# @sync_result.pagination_token: for fetching the next batch of entries using pagination token
+# @sync_result.sync_token: for performing subsequent sync after initial sync
+```
+
+The response also contains a sync token, which you need to store, since this token is used to get subsequent delta updates later, as shown in the Subsequent Sync section below.
+
+You can also fetch custom results in initial sync by using advanced sync queries.
+
+### Sync pagination
+
+If the result of the initial sync (or subsequent sync) contains more than 100 records, the response would be paginated. It provides pagination token in the response. You will need to use this token to get the next batch of data.
+
+```ruby 
+@sync_result = @stack.sync({pagination_token : "<pagination_token>"})
+# @sync_result.items: contains sync data
+# @sync_result.pagination_token: For fetching the next batch of entries using pagination token
+# @sync_result.sync_token: For performing subsequent sync after initial sync
+```
+
+### Subsequent sync
+
+You can use the sync token (that you receive after initial sync) to get the updated content next time. The sync token fetches only the content that was added after your last sync, and the details of the content that was deleted or updated.
+
+```ruby
+@sync_result = @stack.sync({sync_token : "<sync_token>"})
+# @sync_result.items: contains sync data
+# @sync_result.pagination_token: For fetching the next batch of entries using pagination token
+# @sync_result.sync_token: For performing subsequent sync after initial sync
+```
+
+### Advanced sync queries
+
+You can use advanced sync queries to fetch custom results while performing initial sync. 
+[Read advanced sync queries documentation](https://www.contentstack.com/docs/guide/synchronization/using-the-sync-api-with-ruby-sdk#advanced-sync-queries)
+
+
+```ruby
+@sync_result = @stack.sync({init : true, locale: "<locale>" content_type_uid: "<content_type_uid>"})
+# @sync_result.items: contains sync data
+# @sync_result.pagination_token: For fetching the next batch of entries using pagination token
+# @sync_result.sync_token: For performing subsequent sync after initial sync
+```
 ## **Helpful Links**
 
 * [Contentstack Website](https://www.contentstack.com)
@@ -124,7 +187,7 @@ SDK functions for Image Delivery API coming soon.
 
 ## **The MIT License (MIT)**
 
-Copyright © 2012-2020 [Contentstack](https://www.contentstack.com). All Rights Reserved
+Copyright © 2012-2021 [Contentstack](https://www.contentstack.com). All Rights Reserved
 
 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:
 

lib/contentstack/api.rb

@@ -40,6 +40,11 @@ def self.get_assets(asset_uid=nil)
       send_request(path)
     end
 
+    def self.get_sync_items(query)
+      path = "/stacks/sync"
+      send_request(path, query)
+    end
+
     private
     def self.send_request(path, q=nil)
       q ||= {}

lib/contentstack/client.rb

@@ -1,7 +1,7 @@
 require 'contentstack/api'
 require 'contentstack/content_type'
 require 'contentstack/asset_collection'
-
+require 'contentstack/sync_result'
 module Contentstack
   class Client
     attr_reader :region, :host
@@ -11,7 +11,6 @@ def initialize(api_key, delivery_token, environment, options={})
       @host = options[:host].nil? ? get_default_region_hosts(@region) : options[:host]
       API.init_api(api_key, delivery_token, environment,  @host)
     end
-
 
     def content_types
       ContentType.all
@@ -29,6 +28,29 @@ def asset(uid)
       Asset.new(uid)
     end
 
+
+    # Syncs your Contentstack data with your app and ensures that the data is always up-to-date by providing delta updates
+    # 
+    #   Stack.sync({'init': true})        // For initializing sync
+    # 
+    #   Stack.sync({'init': true, 'locale': 'en-us'})     //For initializing sync with entries of a specific locale
+    # 
+    #   Stack.sync({'init': true, 'start_date': '2018-10-22'})    //For initializing sync with entries published after a specific date
+    # 
+    #   Stack.sync({'init': true, 'content_type_uid': 'session'})   //For initializing sync with entries of a specific content type
+    # 
+    #   Stack.sync({'init': true, 'type': 'entry_published'})   // Use the type parameter to get a specific type of content.Supports 'asset_published', 'entry_published', 'asset_unpublished', 'entry_unpublished', 'asset_deleted', 'entry_deleted', 'content_type_deleted'.
+    # 
+    #   Stack.sync({'pagination_token': '<btlsomething>'})    // For fetching the next batch of entries using pagination token
+    # 
+    #   Stack.sync({'sync_token': '<btlsomething>'})    // For performing subsequent sync after initial sync
+    #
+    # @param params [Hash] params is an object that supports ‘locale’, ‘start_date’, ‘content_type_uid’, and ‘type’ queries.
+    def sync(params)
+      sync_result = API.get_sync_items(params)
+      SyncResult.new(sync_result)
+    end
+
     private
     def get_default_region_hosts(region='us')
       case region

lib/contentstack/sync_result.rb

@@ -0,0 +1,30 @@
+require 'active_support/core_ext'
+
+module Contentstack
+  class SyncResult
+    attr_reader :items
+    attr_reader :sync_token
+    attr_reader :pagination_token
+    attr_reader :total_count
+    attr_reader :skip
+    attr_reader :limit
+
+    def initialize(sync_result)
+      if sync_result.nil?
+        @items = []
+        @sync_token = nil
+        @pagination_token = nil
+        @total_count = 0
+        @skip = 0
+        @limit = 100
+      else
+        @items = sync_result["items"] || []
+        @sync_token = sync_result["sync_token"] || nil
+        @pagination_token = sync_result["pagination_token"] || nil
+        @total_count = sync_result["total_count"] || 0
+        @skip = sync_result["skip"] || 0
+        @limit = sync_result["limit"] || 100
+      end
+    end
+  end
+end

lib/contentstack/version.rb

@@ -1,3 +1,3 @@
 module Contentstack
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end