kontent-ai-delivery 3.0.0

data/lib/delivery/client/delivery_query.rb

@@ -0,0 +1,308 @@
+require 'rubygems'
+require 'delivery/builders/url_builder'
+require 'delivery/query_parameters/query_string'
+
+module Kontent
+  module Ai
+    module Delivery
+      # Responsible for executing REST requests to Kontent.ai.
+      class DeliveryQuery
+        ERROR_PREVIEW = 'Preview is enabled for the query, but the key is null. '\
+                        'You can set the preview_key attribute of the query, or '\
+                        'when you initialize the client. See '\
+                        'https://github.com/kontent-ai/delivery-sdk-ruby#previewing-unpublished-content'.freeze
+        ERROR_PARAMS = 'Only filters may be passed in the .item or .items methods'\
+                        '. See https://github.com/kontent-ai/delivery-sdk-ruby#filtering'.freeze
+        HEADER_WAIT_FOR_CONTENT = 'X-KC-Wait-For-Loading-New-Content'.freeze
+        HEADER_SDK_ID = 'X-KC-SDKID'.freeze
+        HEADER_CONTINUATION = 'X-Continuation'.freeze
+        attr_accessor :use_preview,
+                      :preview_key,
+                      :project_id,
+                      :code_name,
+                      :secure_key,
+                      :content_link_url_resolver,
+                      :inline_content_item_resolver,
+                      :query_type,
+                      :query_string,
+                      :content_type,
+                      :with_retry_policy,
+                      :default_rendition_preset
+
+        # Setter for a custom URL.
+        #
+        # * *Args*:
+        #   - *url* (+string+) _optional_ Custom URL to use for the query
+        #
+        # * *Returns*:
+        #   - +self+
+        def url(url = nil)
+          @url = url unless url.nil?
+          self
+        end
+
+        # Constructor. Queries should not be instantiated using the constructor, but
+        # using one of the Kontent::Ai::Delivery::DeliveryClient methods instead.
+        #
+        # * *Args*:
+        #   - *config* (+Hash+) A hash in which each key automatically has its value paired with the corresponding attribute
+        def initialize(config)
+          @headers = {}
+
+          # Map each hash value to attr with corresponding key
+          # from https://stackoverflow.com/a/2681014/5656214
+          config.each do |k, v|
+            instance_variable_set("@#{k}", v) unless v.nil?
+          end
+          self.query_string = Kontent::Ai::Delivery::QueryParameters::QueryString.new
+          return if config.fetch(:qp, nil).nil?
+
+          # Query parameters were passed, parse and validate
+          validate_params config.fetch(:qp)
+        end
+
+        # Executes the REST request.
+        #
+        # * *Returns*:
+        #   - Kontent::Ai::Delivery::Responses::ResponseBase or a class extending it
+        def execute
+          resp = Kontent::Ai::Delivery::RequestManager.start self, headers
+          yield resp if block_given?
+          resp
+        end
+
+        # Determines whether the query should use preview mode.
+        #
+        # * *Returns*:
+        #   - +boolean+ Whether preview mode should be used for the query
+        #
+        # * *Raises*:
+        #   - +StandardError+ if +use_preview+ is true, but +preview_key+ is +nil+
+        def should_preview
+          raise ERROR_PREVIEW if use_preview && preview_key.nil?
+
+          use_preview && !preview_key.nil?
+        end
+
+        # Enables the total_count attribute of the pagination object, which specifies
+        # the total number of items returned by the query regardless of paging. See
+        # https://docs.kontent.ai/reference/delivery-api#operation/list-content-items
+        #
+        # * *Returns*:
+        #   - +self+
+        def include_total_count
+          query_string.set_param('includeTotalCount', 1)
+          self
+        end
+
+        # Sets a content link resolver to render links contained in rich text. See
+        # https://github.com/kontent-ai/delivery-sdk-ruby#resolving-links
+        #
+        # * *Args*:
+        #   - *resolver* ( Kontent::Ai::Delivery::Resolvers::ContentLinkResolver ) The resolver. Replaces a resolver registered during +DeliveryClient+ instantiation, for this query only.
+        #
+        # * *Returns*:
+        #   - +self+
+        def with_link_resolver(resolver)
+          self.content_link_url_resolver = resolver
+          self
+        end
+
+        # Sets an inline content itme to render content items and components in rich text.
+        # See https://github.com/kontent-ai/delivery-sdk-ruby#resolving-inline-content
+        #
+        # * *Args*:
+        #   - *resolver* ( Kontent::Ai::Delivery::Resolvers::InlineContentItemResolver ) The resolver. Replaces a resolver registered during +DeliveryClient+ instantiation, for this query only.
+        #
+        # * *Returns*:
+        #   - +self+
+        def with_inline_content_item_resolver(resolver)
+          self.inline_content_item_resolver = resolver
+          self
+        end
+
+        def with_default_rendition_preset(rendition)
+          self.default_rendition_preset = rendition
+          self
+        end
+
+        # Sets the 'order' query string parameter
+        #
+        # * *Args*:
+        #   - *value* (+string+) The value to order by
+        #   - *sort* (+string+) _optional_ The direction of the order, surrounded by brackets. The default value is '[asc]'
+        #
+        # * *Returns*:
+        #   - +self+
+        def order_by(value, sort = '[asc]')
+          query_string.set_param('order', value + sort)
+          self
+        end
+
+        # Sets the 'skip' query string parameter for paging results.
+        # See https://kontent.ai/learn/reference/delivery-api/#operation/list-content-items
+        #
+        # * *Args*:
+        #   - *value* (+integer+) The number to skip by
+        #
+        # * *Returns*:
+        #   - +self+
+        def skip(value)
+          query_string.set_param('skip', value) unless query_type.eql? Kontent::Ai::Delivery::QUERY_TYPE_ITEMS_FEED
+          self
+        end
+
+        # Sets the 'language' query string parameter. Language fallbacks will be used
+        # if untranslated content items are found.
+        # See https://kontent.ai/learn/tutorials/develop-apps/get-content/localized-content-items/
+        #
+        # * *Args*:
+        #   - *value* (+string+) The code name of the desired language
+        #
+        # * *Returns*:
+        #   - +self+
+        def language(value)
+          query_string.set_param('language', value)
+          self
+        end
+
+        # Sets the 'limit' query string parameter for paging results, or just to
+        # return a specific number of content items.
+        # See https://kontent.ai/learn/reference/delivery-api/#operation/list-content-items
+        #
+        # * *Args*:
+        #   - *value* (+integer+) The number of content items to return
+        #
+        # * *Returns*:
+        #   - +self+
+        def limit(value)
+          query_string.set_param('limit', value) unless query_type.eql? Kontent::Ai::Delivery::QUERY_TYPE_ITEMS_FEED
+          self
+        end
+
+        # Sets the 'elements' query string parameter to limit the elements returned
+        # by the query.
+        # See https://kontent.ai/learn/reference/delivery-api/#tag/Projection
+        #
+        # * *Args*:
+        #   - *value* (+Array+) A single string or array of strings specifying the desired elements, e.g. %w[price product_name image]
+        #
+        # * *Returns*:
+        #   - +self+
+        def elements(value)
+          query_string.set_param('elements', value)
+          self
+        end
+
+        # Sets the 'depth' query string parameter to determine how many levels of
+        # linked content items should be returned. By default, only 1 level of depth
+        # is used.
+        # See https://kontent.ai/learn/reference/delivery-api/#tag/Linked-content-and-components/linked-content-depth
+        #
+        # * *Args*:
+        #   - *value* (+integer+) Level of linked items to be returned
+        #
+        # * *Returns*:
+        #   - +self+
+        def depth(value)
+          query_string.set_param('depth', value) unless query_type.eql? Kontent::Ai::Delivery::QUERY_TYPE_ITEMS_FEED
+          self
+        end
+
+        # Allows the request to bypass caching and return the latest content
+        # directly from Kontent.ai.
+        # See https://github.com/kontent-ai/delivery-sdk-ruby#requesting-the-latest-content
+        #
+        # * *Returns*:
+        #   - +self+
+        def request_latest_content
+          @headers[HEADER_WAIT_FOR_CONTENT] = true
+          self
+        end
+
+        # Uses Kontent::Ai::Delivery::Builders::UrlBuilder.provide_url to set
+        # the URL for the query. The +UrlBuilder+ also validates the URL.
+        #
+        # * *Raises*:
+        #   - +UriFormatException+ if the URL is 65,519 characters or more
+        #
+        # * *Returns*:
+        #   - +string+ The full URL for this query
+        def provide_url
+          @url = Kontent::Ai::Delivery::Builders::UrlBuilder.provide_url self if @url.nil?
+          Kontent::Ai::Delivery::Builders::UrlBuilder.validate_url @url
+          @url
+        end
+
+        # Allows providing custom headers for client requests.
+        # See https://github.com/kontent-ai/delivery-sdk-ruby#providing-custom-headers
+        #
+        # * *Args*:
+        #   - *headers* (+Hash+) A hash that corresponds to provided headers
+        #
+        # * *Returns*:
+        #   - +self+
+        def custom_headers(headers)
+          @custom_headers = headers
+          self
+        end
+
+        def update_continuation(token)
+          @headers[HEADER_CONTINUATION] = token
+          self
+        end
+
+        def continuation_exists?
+          !continuation_token.nil?
+        end
+
+        def continuation_token
+          @headers[HEADER_CONTINUATION]
+        end
+
+        private
+
+        # Returns request headers that are extended with custom headers.
+        # Custom headers do not override existing headers.
+        #
+        # * *Returns*
+        #   - +Hash+
+        def headers
+          headers = @headers.clone
+          headers[HEADER_SDK_ID] = provide_sdk_header
+          headers['Authorization'] = "Bearer #{preview_key}" if should_preview
+          headers['Authorization'] = "Bearer #{secure_key}" if !should_preview && secure_key
+
+          if @custom_headers
+            headers.merge!(@custom_headers) { |key, v1, v2| v1 }
+          end
+
+          headers
+        end
+
+        # Initializes the +query_string+ attribute with the passed array of
+        # Kontent::Ai::Delivery::QueryParameters::Filter objects.
+        #
+        # * *Raises*:
+        #   - +ArgumentError+ if one the passed objects is not a +Filter+
+        def validate_params(query_parameters)
+          params = if query_parameters.is_a? Array
+                    query_parameters
+                  else
+                    [query_parameters]
+                  end
+          params.each do |p|
+            query_string.set_param p
+            unless p.is_a? Kontent::Ai::Delivery::QueryParameters::Filter
+              raise ArgumentError, ERROR_PARAMS
+            end
+          end
+        end
+
+        def provide_sdk_header
+          'rubygems.org;delivery-sdk-ruby;'
+        end
+      end
+    end
+  end
+end

data/lib/delivery/client/request_manager.rb

@@ -0,0 +1,127 @@
+require 'rest-client'
+
+module Kontent
+  module Ai
+    module Delivery
+      class RequestManager
+        class << self
+          MAX_ATTEMPTS = 6
+          MAX_DELAY_SECONDS = 30
+          INITIAL_DELAY = 1
+          RETRY_WHEN_CODE = [408, 429, 500, 502, 503, 504].freeze
+          CODES_WITH_POSSIBLE_RETRY_HEADER = [429, 503].freeze
+
+          def start(query, headers)
+            @query = query
+            @headers = headers
+            @times_run = 1
+            @delay = INITIAL_DELAY
+            @url = @query.provide_url
+            @total_delay = 0
+            continue
+          end
+
+          private
+
+          def should_retry(potential_response)
+            return potential_response if @times_run == MAX_ATTEMPTS ||
+                                         !RETRY_WHEN_CODE.include?(potential_response.http_code) ||
+                                         !@query.with_retry_policy ||
+                                         @total_delay >= MAX_DELAY_SECONDS
+
+            next_delay
+            sleep(@delay)
+            @total_delay += @delay
+            continue
+          end
+
+          # Generates a random delay based on times_run, then increases times_run
+          def next_delay
+            min = 0.8 * INITIAL_DELAY
+            max = (1.2 * INITIAL_DELAY) * (2**@times_run)
+            @delay = rand(min..max)
+            @times_run += 1
+          end
+
+          def continue
+            if ENV['TEST'] == '1'
+              resp = Kontent::Ai::Delivery::Tests::FakeResponder.get_response @query, @url, @headers
+              return should_retry(resp) if resp.is_a? Kontent::Ai::Delivery::Responses::ResponseBase
+
+              make_response resp # resp is pure JSON
+            else
+              begin
+                resp = RestClient.get @url, @headers
+              rescue RestClient::ExceptionWithResponse => err
+                should_retry Kontent::Ai::Delivery::Responses::ResponseBase.new err.http_code, err.response
+              rescue RestClient::SSLCertificateNotVerified => err
+                should_retry Kontent::Ai::Delivery::Responses::ResponseBase.new 500, err
+              rescue SocketError => err
+                should_retry Kontent::Ai::Delivery::Responses::ResponseBase.new 500, err.message
+              else
+                make_response resp
+              end
+            end
+          end
+
+          # Converts a standard REST response based on the type of query.
+          #
+          # * *Returns*:
+          #   - An object derived from the Kontent::Ai::Delivery::Responses::ResponseBase class
+          def make_response(response)
+            case @query.query_type
+            when Kontent::Ai::Delivery::QUERY_TYPE_ITEMS_FEED
+              Kontent::Ai::Delivery::Responses::DeliveryItemsFeedResponse.new(
+                response.headers,
+                response.body,
+                @query
+              )
+            when Kontent::Ai::Delivery::QUERY_TYPE_ITEMS
+              respond_item response
+            when Kontent::Ai::Delivery::QUERY_TYPE_TYPES
+              respond_type response
+            when Kontent::Ai::Delivery::QUERY_TYPE_TAXONOMIES
+              respond_taxonomy response
+            when Kontent::Ai::Delivery::QUERY_TYPE_ELEMENT
+              Kontent::Ai::Delivery::Responses::DeliveryElementResponse.new response.headers, response.body
+            when Kontent::Ai::Delivery::QUERY_TYPE_LANGUAGES
+              Kontent::Ai::Delivery::Responses::DeliveryLanguageListingResponse.new response.headers, response.body
+            end
+          end
+
+          def respond_type(response)
+            if @query.code_name.nil?
+              Kontent::Ai::Delivery::Responses::DeliveryTypeListingResponse.new response.headers, response.body
+            else
+              Kontent::Ai::Delivery::Responses::DeliveryTypeResponse.new response.headers, response.body
+            end
+          end
+
+          def respond_taxonomy(response)
+            if @query.code_name.nil?
+              Kontent::Ai::Delivery::Responses::DeliveryTaxonomyListingResponse.new response.headers, response.body
+            else
+              Kontent::Ai::Delivery::Responses::DeliveryTaxonomyResponse.new response.headers, response.body
+            end
+          end
+
+          def respond_item(response)
+            if @query.code_name.nil?
+              Kontent::Ai::Delivery::Responses::DeliveryItemListingResponse.new(
+                response.headers,
+                response.body,
+                @query
+              )
+            else
+              Kontent::Ai::Delivery::Responses::DeliveryItemResponse.new(
+                response.headers,
+                response.body,
+                @query
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/models/content_item.rb

@@ -0,0 +1,153 @@
+require 'ostruct'
+require 'nokogiri'
+
+module Kontent
+  module Ai
+    module Delivery
+      class ContentItem
+        attr_accessor :content_link_url_resolver,
+                      :inline_content_item_resolver
+
+        # Parses the 'elements' JSON object as a dynamic OpenStruct object.
+        #
+        # * *Returns*:
+        #   - +OpenStruct+ The elements of the content item
+        def elements
+          @elements unless @elements.nil?
+          @elements = JSON.parse(
+            JSON.generate(@source['elements']),
+            object_class: OpenStruct
+          )
+        end
+
+        # Parses the 'system' JSON object as a dynamic OpenStruct object.
+        #
+        # * *Returns*:
+        #   - +OpenStruct+ The system properties of the content item
+        def system
+          @system unless @system.nil?
+          @system = JSON.parse(
+            JSON.generate(@source['system']),
+            object_class: OpenStruct
+          )
+        end
+
+        # Constructor.
+        #
+        # * *Args*:
+        #   - *source* (+JSON+) The response from a REST request for content items. The item may be on the root or under the 'item' node
+        #   - *content_link_url_resolver* ( Kontent::Ai::Delivery::Resolvers::ContentLinkResolver )
+        #   - *inline_content_item_resolver* ( Kontent::Ai::Delivery::Resolvers::InlineContentItemResolver )
+        #   - *linked_items_resolver* ( Kontent::Ai::Delivery::Resolvers::LinkedItemResolver )
+        def initialize(source, content_link_url_resolver, inline_content_item_resolver, linked_items_resolver)
+          @source =
+            if source['item'].nil?
+              source
+            else
+              source['item']
+            end
+          @linked_items_resolver = linked_items_resolver
+          self.content_link_url_resolver = content_link_url_resolver
+          self.inline_content_item_resolver = inline_content_item_resolver
+        end
+
+        # Gets a string representation of the data stored in the element. Using this
+        # method instead of directly accessing the +elements+ collection causes
+        # the content to be resolved using the resolvers passed during instantiation.
+        # See https://github.com/kontent-ai/delivery-sdk-ruby#resolving-links
+        #
+        # * *Args*:
+        #   - *code_name* (+string+) The code name of the desired element
+        #
+        # * *Returns*:
+        #   - +string+ The data converted to a string, resolved if the element is a 'rich_text' element
+        def get_string(code_name)
+          element = get_element code_name
+          content = element['value']
+
+          if element['type'] == 'rich_text'
+            content = content_link_url_resolver.resolve content, element['links'] if should_resolve_links element
+            inline_items = get_inline_items code_name
+            content = inline_content_item_resolver.resolve content, inline_items if should_resolve_inline_content element
+          end
+          content.to_s
+        end
+
+        # Returns an array of assets inserted into the specified element of the
+        # 'asset' type.
+        #
+        # * *Args*:
+        #   - *code_name* (+string+) The code name of the desired element
+        #
+        # * *Returns*:
+        #   - +Array+ The element's assets parsed as +OpenStruct+ objects
+        def get_assets(code_name)
+          element = get_element code_name
+          element['value'].map { |n| OpenStruct.new(n) }
+        end
+
+        # Returns an array of ContentItems that are linked in a 'modular_content'
+        # element.
+        #
+        # * *Args*:
+        #   - *code_name* (+string+) The code name of the desired element
+        #
+        # * *Returns*:
+        #   - +Array+ The element's linked items parsed as +ContentItem+ objects
+        def get_links(code_name)
+          element = get_element code_name
+          get_linked_items element['value']
+        end
+
+        # Returns an array of ContentItems that are inserted as inline content
+        # items or componenets of a 'rich_text' element.
+        #
+        # * *Args*:
+        #   - *code_name* (+string+) The code name of the desired element
+        #
+        # * *Returns*:
+        #   - +Array+ The element's inline content items parsed as +ContentItem+ objects
+        def get_inline_items(code_name)
+          element = get_element code_name
+          get_linked_items element['modular_content']
+        end
+
+        private
+
+        def should_resolve_links(element)
+          !element['links'].nil? && !content_link_url_resolver.nil?
+        end
+
+        def should_resolve_inline_content(element)
+          !element['modular_content'].nil? && !inline_content_item_resolver.nil?
+        end
+
+        # Gets the JSON object from the 'elements' collection with the specified key
+        #
+        # * *Args*:
+        #   - *code_name* (+string+, +symbol+) The code name or symbol of the desired element
+        #
+        # * *Returns*:
+        #   - +JSON+ The element as a JSON object
+        #
+        # * *Raises*:
+        #   - +ArgumentError+ if +code_name+ is +nil+
+        def get_element(code_name)
+          raise ArgumentError, "Argument 'code_name' cannot be null" if code_name.nil?
+
+          code_name = code_name.to_s if code_name.is_a? Symbol
+          @source['elements'][code_name]
+        end
+
+        def get_linked_items(codenames)
+          return [] unless codenames.class == Array
+
+          codenames.each_with_object([]) do |codename, items|
+            item = @linked_items_resolver.resolve codename
+            items << item if item
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/models/content_type.rb

@@ -0,0 +1,41 @@
+require 'ostruct'
+
+module Kontent
+  module Ai
+    module Delivery
+      class ContentType
+        # Parses the 'elements' JSON object as a dynamic OpenStruct object.
+        #
+        # * *Returns*:
+        #   - +OpenStruct+ The elements of the content type
+        def elements
+          @elements unless @elements.nil?
+          @elements = JSON.parse(
+            JSON.generate(@source['elements']),
+            object_class: OpenStruct
+          )
+        end
+
+        # Parses the 'system' JSON object as a dynamic OpenStruct object.
+        #
+        # * *Returns*:
+        #   - +OpenStruct+ The system properties of the content type
+        def system
+          @system unless @system.nil?
+          @system = JSON.parse(
+            JSON.generate(@source['system']),
+            object_class: OpenStruct
+          )
+        end
+
+        # Constructor.
+        #
+        # * *Args*:
+        #   - *source* (+JSON+) The response from a REST request for content types
+        def initialize(source)
+          @source = source
+        end
+      end
+    end
+  end
+end

data/lib/delivery/models/language.rb

@@ -0,0 +1,29 @@
+require 'ostruct'
+
+module Kontent
+  module Ai
+    module Delivery
+      class Language
+        # Parses the 'system' JSON object as a dynamic OpenStruct object.
+        #
+        # * *Returns*:
+        #   - +OpenStruct+ The system properties of the language
+        def system
+          @system unless @system.nil?
+          @system = JSON.parse(
+            JSON.generate(@source['system']),
+            object_class: OpenStruct
+          )
+        end
+
+        # Constructor.
+        #
+        # * *Args*:
+        #   - *source* (+JSON+) The response from a REST request for a language
+        def initialize(source)
+          @source = source
+        end
+      end
+    end
+  end
+end

data/lib/delivery/models/pagination.rb

@@ -0,0 +1,22 @@
+module Kontent
+  module Ai
+    module Delivery
+      # Holds pagination data from listing responses
+      class Pagination
+        attr_accessor :skip, :limit, :count, :next_page, :total_count
+
+        # Constructor.
+        #
+        # * *Args*:
+        #   - *json* (+JSON+) The 'pagination' node of a listing reponse's JSON object 
+        def initialize(json)
+          self.skip = json['skip']
+          self.limit = json['limit']
+          self.count = json['count']
+          self.next_page = json['next_page']
+          self.total_count = json['total_count']
+        end
+      end
+    end
+  end
+end