contentstack 0.0.3 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 1ba9cac23e4e20c7af32bb25d788cd226f489bb9
-  data.tar.gz: '0903ec191fca15f8664db5c9de793453657b3636'
+SHA256:
+  metadata.gz: ed2009d779c953b80883a4d8c8d267cca918c3a784450513643f308ae79645c1
+  data.tar.gz: 4a48fc25a61c332e8f338941828b87836db709eb0c7f819b5e926f1d264ae5d7
 SHA512:
-  metadata.gz: '068954e3aac1861e09fe135fbcea77ac2fd528e8e295285bed5286026a1202fbd10f78f9418a7c1c5a8af14f8a9bfa107a7568567b9cb907c09374dae93415c3'
-  data.tar.gz: b38b4b0320cf45944edd04c6c0aed62578d9b029141f1b159f0dcf51e778a852623a4e06b270f11fdf5dd21613cdc41386614102c987426da2f9e02c2a202f1b
+  metadata.gz: 1c74b89fabfe984e5d068cc6a1c1dcf40b8d098730959677572e71f7f6c0f989bd82d131b87f23f66f83a80c73104197fa008d7ba3685baaf491f2fe214f829a
+  data.tar.gz: e3d42fd8f4fc573a08dae949fe85d0576a7bc9290e724941468439f8afe4093f979b7f992c0572667e0942fe7a9c262ca8b3c42d13f5a7d8c762c9e02695f39a

data/.gitignore

@@ -5,3 +5,7 @@ doc
 spec-integration
 coverage
 \.yardoc
+.DS_Store
+.bundle/
+*/rspec_results.html
+vendor/

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+## CHANGELOG
+------------------------------------------------
+
+## Version 0.3.0
+### Date: 17th-Mar-2021
+ ### New Features
+ - Sync API module support added
+
+ ------------------------------------------------
+## Version 0.2.0
+
+ ### New Features
+  - Entry 
+    - locale - function for passing locale is added
+    - only - function for getting only specified field
+    - except - function for getting field except specified field
+    - include_reference - function for including reference in entry
+    - include_schema - function for including schema along with entry added
+    - include_content_type - function for including content type details along with entry added
+    - include_owner - function for getting owner of entry
+    - include_fallback - function for getting published fallback locale content, if specified locale content is not published
+
+  - Query 
+    - include_fallback - function for getting published fallback locale content, if specified locale content is not published
+
+
+------------------------------------------------
+
+## Version 0.1.0
+
+ ### Bug
+  - Stack Tokens Moved to Headers
+
+------------------------------------------------
+
+## Version 0.0.4
+
+ ### Enhancement
+  - Region support added
+
+------------------------------------------------
+
+## Version 0.0.3
+
+ ### Enhancement
+  - Query - function for passing locale is added.
+
+------------------------------------------------
+
+## Version 0.0.1
+
+ - Initial release 
+
+------------------------------------------------

data/CODE_OF_CONDUCT.md

@@ -22,8 +22,7 @@ include:
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
-advances
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
 * Trolling, insulting/derogatory comments, and personal or political attacks
 * Public or private harassment
 * Publishing others' private information, such as a physical or electronic

data/Gemfile

@@ -0,0 +1,8 @@
+# Gemfile
+source "https://rubygems.org"
+
+gem "rspec"
+gem "webmock"
+gem "simplecov"
+gem "activesupport"
+gem "yard"

data/Gemfile.lock

@@ -0,0 +1,61 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (6.0.3.1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.0)
+    concurrent-ruby (1.1.6)
+    crack (0.4.3)
+      safe_yaml (~> 1.0.0)
+    diff-lcs (1.3)
+    docile (1.3.2)
+    hashdiff (1.0.1)
+    i18n (1.8.2)
+      concurrent-ruby (~> 1.0)
+    minitest (5.14.1)
+    public_suffix (4.0.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.1)
+      rspec-support (~> 3.9.1)
+    rspec-expectations (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.2)
+    safe_yaml (1.0.5)
+    simplecov (0.18.5)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+    simplecov-html (0.12.2)
+    thread_safe (0.3.6)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    webmock (3.8.3)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.25)
+    zeitwerk (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport
+  rspec
+  simplecov
+  webmock
+  yard
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016 amite
+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

data/README.md

@@ -19,8 +19,16 @@ 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.
-
-    client = Contentstack::Client.new("site_api_key", "access_token", "enviroment_name")
+```ruby
+    # with default region
+    client = Contentstack::Client.new("api_key", "delivery_token", "enviroment_name")
+    
+    # with specific region
+    client = Contentstack::Client.new("api_key", "delivery_token", "enviroment_name",{"region": Contentstack::Region::EU})
+    
+    # with custom host
+    client = Contentstack::Client.new("api_key", "delivery_token", "enviroment_name",{"host": "https://custom-cdn.contentstack.com"})
+```
 
 ## **Key Concepts for using Contentstack**
 
@@ -46,23 +54,44 @@ A publishing environment corresponds to one or more deployment servers or a cont
 
 ## **Contentstack Ruby SDK: 5-minute Quickstart**
 
-### **Initializing your SDK **
+### **Initializing your SDK**
 
 To initialize the SDK, you need to provide values for the keys given in the snippet below:
-
-    stack = Contentstack::Client.new("site_api_key", "access_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')}" }
+```
+
+To retrieve localized versions of entries, you can use the query attribute:
+```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**
 
@@ -70,6 +99,19 @@ You can query for content types, entries, assets and more using our Ruby API Ref
 
 [Ruby API Reference Doc](http://www.rubydoc.info/gems/contentstack)
 
+### 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.
+
+```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.
+
 ## **Working with Images**
 
 We have introduced Image Delivery APIs that let you retrieve images and then manipulate and optimize them for your digital properties. It lets you perform a host of other actions such as crop, trim, resize, rotate, overlay, and so on. 
@@ -78,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)
@@ -90,7 +187,7 @@ SDK functions for Image Delivery API coming soon.
 
 ## **The MIT License (MIT)**
 
-Copyright © 2012-2017 [Built.io](https://www.built.io/). 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:
 

data/contentstack.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 2.0'
 
   s.license = "MIT"
-  s.homepage = "https://github.com/builtio-contentstack/contentstack-ruby"
+  s.homepage = "https://github.com/contentstack/contentstack-ruby"
 
   s.summary = %q{Contentstack Ruby client for the Content Delivery API}
   s.description = %q{Contentstack Ruby client for the Content Delivery API}

data/lib/contentstack.rb

@@ -2,15 +2,20 @@ $LOAD_PATH.unshift File.expand_path("../../lib", __FILE__)
 
 require "contentstack/version"
 require "contentstack/client"
+require "contentstack/region"
 require "util"
 
 
-# == Built.io Contentstack - Ruby SDK
-# Built.io Contentstack is a content management system that facilitates the process of publication by separating the content from site-related programming and design.
+# == Contentstack - Ruby SDK
+# Contentstack is a content management system that facilitates the process of publication by separating the content from site-related programming and design.
 # == Installation
 #   gem install contentstack
 # == Initialize the Stack
-#   @stack = Contentstack::Client.new("site_api_key", "access_token", "enviroment_name")
+#   @stack = Contentstack::Client.new("site_api_key", "delivery_token", "enviroment_name")
+# == Initialize the Stack for EU region
+#   @stack = Contentstack::Client.new("site_api_key", "delivery_token", "enviroment_name", {"region": Contentstack::Region::EU })
+# == Initialize the Stack for custom host
+#   @stack = Contentstack::Client.new("site_api_key", "delivery_token", "enviroment_name", {"host": "https://custom-cdn.contentstack.com" })
 # == Usage
 # ==== Get single entry
 #   @stack.content_type('blog').entry('<entry_uid_here>').fetch

data/lib/contentstack/api.rb

@@ -6,11 +6,13 @@ require 'open-uri'
 
 module Contentstack
   class API
-    def self.init_api(api_key, access_token, environment)
-      @host = "https://cdn.contentstack.io"
+    def self.init_api(api_key, delivery_token, environment,host)
+      @host = host
       @api_version = '/v3'
       @environment = environment
-      @headers = {api_key: api_key, access_token: access_token, user_agent: "ruby-sdk/#{Contentstack::VERSION}", environment: @environment}
+      @api_key = api_key
+      @access_token = delivery_token
+      @headers = {environment: @environment}
     end
 
     def self.fetch_content_types(uid="")
@@ -27,9 +29,9 @@ module Contentstack
       send_request(path, query)
     end
 
-    def self.fetch_entry(content_type, entry_uid)
+    def self.fetch_entry(content_type, entry_uid, query)
       path = "/content_types/#{content_type}/entries/#{entry_uid}"
-      send_request(path)
+      send_request(path, query)
     end
 
     def self.get_assets(asset_uid=nil)
@@ -38,17 +40,25 @@ module Contentstack
       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 ||= {}
 
       q.merge!(@headers)
-      q.merge!({timestamp: Time.now.to_i})
 
       query = "?" + q.to_query
       # puts "Request URL:- #{@host}#{@api_version}#{path}#{query} \n\n"
       
-      ActiveSupport::JSON.decode(open("#{@host}#{@api_version}#{path}#{query}").read)
+      ActiveSupport::JSON.decode(open("#{@host}#{@api_version}#{path}#{query}",
+      "api_key" =>  @api_key,
+      "access_token"=>  @access_token,
+      "user_agent"=> "ruby-sdk/#{Contentstack::VERSION}",
+      "x-user-agent" => "ruby-sdk/#{Contentstack::VERSION}").read)
     end
   end
-end
+end

data/lib/contentstack/client.rb

@@ -1,14 +1,16 @@
 require 'contentstack/api'
 require 'contentstack/content_type'
 require 'contentstack/asset_collection'
-
+require 'contentstack/sync_result'
 module Contentstack
   class Client
-    # Initialize "Built.io Contentstack" Client instance
-    def initialize(api_key, access_token, environment)
-      API.init_api(api_key, access_token, environment)
+    attr_reader :region, :host
+    # Initialize "Contentstack" Client instance
+    def initialize(api_key, delivery_token, environment, options={})
+      @region = options[:region].nil? ? Contentstack::Region::US : options[:region]
+      @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
@@ -25,5 +27,39 @@ module Contentstack
     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
+      when "us"
+        host = "https://cdn.contentstack.io"
+      when "eu"
+        host = "https://eu-cdn.contentstack.com"
+      end
+      host
+    end
   end
 end