kontent-ai-delivery 3.0.0

data/lib/delivery/models/taxonomy_group.rb

@@ -0,0 +1,39 @@
+module Kontent
+  module Ai
+    module Delivery
+      class TaxonomyGroup
+        # Parses the 'terms' JSON node as a dynamic OpenStruct object.
+        #
+        # * *Returns*:
+        #   - +OpenStruct+ The terms of the taxonomy group as a dynamic object
+        def terms
+          @terms unless @terms.nil?
+          @terms = JSON.parse(
+            JSON.generate(@source['terms']),
+            object_class: OpenStruct
+          )
+        end
+
+        # Parses the 'system' JSON node as a dynamic OpenStruct object.
+        #
+        # * *Returns*:
+        #   - +OpenStruct+ The system properties of the taxonomy group
+        def system
+          @system unless @system.nil?
+          @system = JSON.parse(
+            JSON.generate(@source['system']),
+            object_class: OpenStruct
+          )
+        end
+
+        # Constructor.
+        #
+        # * *Args*:
+        #   - *json* (+JSON+) A JSON node representing a taxonomy group
+        def initialize(source)
+          @source = source
+        end
+      end
+    end
+  end
+end

data/lib/delivery/query_parameters/filters.rb

@@ -0,0 +1,201 @@
+require 'delivery/query_parameters/parameter_base'
+
+module Kontent
+  module Ai
+    module Delivery
+      module QueryParameters
+        # Provides the base class for filter implementations.
+        # See https://kontent.ai/learn/reference/delivery-api/#tag/Filtering-content
+        class Filter < ParameterBase
+          # Constructor.
+          #
+          # * *Args*:
+          #   - *key* (+string+) The field to filter upon
+          #   - *operator* (+string+) The Kontent.ai filter being applied to the field, in brackets
+          #   - *values* (+Object+) One or more values which will appear as the value of the query string parameter
+          #   - *eq_sign* (+boolean+) If false, the equals sign is not generated in the parameter
+          def initialize(key, operator, values, eq_sign = true)
+            super(key, operator, values, eq_sign)
+          end
+        end
+      end
+    end
+  end
+end
+
+# Extend String class to allow semantic typing of filters
+class String
+  # Represents a filter that matches a content item if the specified content
+  # element or system attribute has a value that contains all the specified
+  # values. This filter is applicable to array values only, such as sitemap
+  # location or value of Linked Items, Taxonomy and Multiple choice content elements.
+  #
+  # * *Args*:
+  #   - +Object+ One or more objects representing the values that must appear in the field
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def all(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[all]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified content
+  # element or system attribute has a value that contains any the specified
+  # values. This filter is applicable to array values only, such as sitemap
+  # location or value of Linked Items, Taxonomy and Multiple choice content elements.
+  #
+  # * *Args*:
+  #   - +Object+ One or more objects representing the values that may appear in the field
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def any(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[any]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified content element
+  # or system attribute has a value that contains the specified value.
+  # This filter is applicable to array values only, such as sitemap location or value
+  # of Linked Items, Taxonomy and Multiple choice content elements.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the value that must appear in the field
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def contains(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[contains]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified
+  # content element or system attribute has the specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the value that must equal the value in the field
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def eq(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified
+  # content element or system attribute does not have the specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the value that cannot exist in the element
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def not_eq(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[neq]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified
+  # content element or system attribute does not have any value.
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def empty
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[empty]', nil, false)
+  end
+
+  # Represents a filter that matches a content item if the specified
+  # content element or system attribute has any value.
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def not_empty
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[nempty]', nil, false)
+  end
+
+  # Represents a filter that matches a content item if the specified
+  # content element or system attribute does not have the specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the value that cannot exist in the element
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def not_in(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[nin]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified content
+  # element or system attribute has a value that is greater than the
+  # specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the lowest possible value of the field, non-inclusive
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def gt(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[gt]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified content
+  # element or system attribute has a value that is greater than or equal to
+  # the specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the lowest possible value of the field
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def gt_or_eq(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[gte]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified
+  # content element or system attribute has a value that matches a
+  # value in the specified list.
+  #
+  # * *Args*:
+  #   - +Object+ One or more objects representing the required values of the field
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def in(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[in]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified content
+  # element or system attribute has a value that is less than the
+  # specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the highest possible value of the field, non-inclusive
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def lt(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[lt]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified content
+  # element or system attribute has a value that is less than or equal to
+  # the specified value.
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the highest possible value of the field
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def lt_or_eq(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[lte]', *args)
+  end
+
+  # Represents a filter that matches a content item if the specified
+  # content element or system attribute has a value that falls within
+  # the specified range of values (both inclusive).
+  #
+  # * *Args*:
+  #   - +Object+ An object representing the lowest and highest possible values of the field
+  #
+  # * *Returns*:
+  #   - Kontent::Ai::Delivery::QueryParameters::Filter
+  def range(*args)
+    Kontent::Ai::Delivery::QueryParameters::Filter.new(self, '[range]', *args)
+  end
+end

data/lib/delivery/query_parameters/parameter_base.rb

@@ -0,0 +1,56 @@
+require 'cgi'
+
+module Kontent
+  module Ai
+    module Delivery
+      module QueryParameters
+        # Base class for all parameters added to a DeliveryQuery. All
+        # QueryParameters will appear in the query string.
+        class ParameterBase
+          attr_accessor :key
+          SEPARATOR = CGI::escape(',')
+
+          # Constructor.
+          #
+          # * *Args*:
+          #   - *key* (+string+) The field to filter upon
+          #   - *operator* (+string+) The Kontent.ai filter being applied to the field, in brackets
+          #   - *values* (+Object+) One or more values which will appear as the value of the query string parameter
+          #   - *eq_sign* (+boolean+) If false, the equals sign is not generated in the parameter
+          def initialize(key, operator, values, eq_sign = true)
+            self.key = key
+            values = [values] unless values.respond_to? :each
+            @values = values
+            @operator = operator
+            @eq_sign = eq_sign
+          end
+
+          # Converts the object into a valid query string parameter for use in
+          # a request to Delivery. The key, operator, and values are all escaped
+          # and if there are multiple values, they are joined with commas.
+          #
+          # * *Returns*:
+          #   - +string+ A query string parameter without any additional characters (e.g. '&')
+          def provide_query_string_parameter
+            escaped_values = []
+            @values.each { |n| escaped_values << CGI.escape(n.to_s) }
+            if @eq_sign 
+              format(
+                '%<k>s%<o>s=%<v>s',
+                k: CGI.escape(key),
+                o: CGI.escape(@operator),
+                v: escaped_values.join(SEPARATOR)
+              )
+            else
+              format(
+                '%<k>s%<o>s',
+                k: CGI.escape(key),
+                o: CGI.escape(@operator)
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/query_parameters/query_string.rb

@@ -0,0 +1,78 @@
+require 'delivery/query_parameters/parameter_base'
+
+module Kontent
+  module Ai
+    module Delivery
+      module QueryParameters
+        # Represents the entire query string for a request to Delivery.
+        class QueryString
+          def initialize
+            @params = []
+          end
+
+          # Adds a parameter to the query string
+          #
+          # * *Args*:
+          #   - *param* (+Object+) Either a string representing the key for the parameter, or a complete Kontent::Ai::Delivery::QueryParameters::ParameterBase object
+          #   - *values* (+string+) A string or array of strings representing the values for the parameter
+          #   - *operator* (+string+) Kontent.ai filtering parameter, placed after the key, before the equal sign
+          def set_param(param, values = '', operator = '')
+            parameter_base =
+              if param.is_a? String
+                Kontent::Ai::Delivery::QueryParameters::ParameterBase.new(
+                  param,
+                  operator,
+                  values
+                )
+              else
+                param
+              end
+            # Ensure we have a ParameterBase object
+            return unless parameter_base.respond_to? 'provide_query_string_parameter'
+
+            remove_param parameter_base.key
+            @params << parameter_base
+          end
+
+          # Removes all parameters from the query string with a matching key.
+          #
+          # * *Args*:
+          #   - *key* (+string+) Parameter key
+          def remove_param(key)
+            @params.delete_if { |i| i.key.eql? key }
+          end
+
+          # Returns all parameters from the query string with a matching key.
+          #
+          # * *Args*:
+          #   - *key* (+string+) Parameter key
+          #
+          # * *Returns*:
+          #   - +Object+ One or more Kontent::Ai::Delivery::QueryParameters::ParameterBase objects
+          def param(key)
+            @params.select { |p| p.key.eql? key }
+          end
+
+          # Checks whether there are any parameters defined.
+          #
+          # * *Returns*:
+          #   - +bool+ True if there are no parameters set.
+          def empty?
+            @params.empty?
+          end
+
+          # Generates a full query string based on the set parameters, with the
+          # required '?' character at the start. Accomplished by calling the
+          # Kontent::Ai::Delivery::QueryParameters::ParameterBase.provide_query_string_parameter
+          # method for each parameter.
+          #
+          # * *Returns*:
+          #   - +string+ A complete query string
+          def to_s
+            '?' + @params.map(&:provide_query_string_parameter).join('&')
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/resolvers/content_link_resolver.rb

@@ -0,0 +1,102 @@
+require 'nokogiri'
+
+module Kontent
+  module Ai
+    module Delivery
+      module Resolvers
+        # Locates <a data-item-id=""> tags in content and calls a user-defined method
+        # to supply the href for content item links.
+        # See https://github.com/kontent-ai/delivery-sdk-ruby#resolving-links
+        class ContentLinkResolver
+          # Constructor.
+          #
+          # * *Args*:
+          #   - *found_handler* (+lambda+) _optional_ Method to be called when resolving a content link and the content item is present in the response
+          #   - *not_found_handler* (+lambda+) _optional_ Method to be called when resolving a content link and the content item isn't present in the response
+          def initialize(found_handler = nil, not_found_handler = nil)
+            @found_handler = found_handler
+            @not_found = not_found_handler
+          end
+
+          # Resolves all links in the content.
+          #
+          # * *Args*:
+          #   - *content* (+string+) The string value stored in the element
+          #   - *links* (+Array+) The collection of links from an element's 'links' JSON node
+          #
+          # * *Returns*:
+          #   - +string+ The original content passed, with all links resolved
+          def resolve(content, links)
+            doc = Nokogiri::HTML.parse(content).xpath('//body')
+            links = links.map { |link| ContentLink.new link }
+            tags = doc.xpath('//a[@data-item-id]')
+            # This line performs the link resolving and replaces the tags in doc
+            tags.map { |tag| resolve_tag tag, links }
+            doc.to_xhtml
+          end
+
+          private
+
+          # Accepts a tag found in the content and tries to locate matching
+          # source link from JSON response. If found, resolves URL and returns
+          # the tag with generated HREF.
+          #
+          # * *Args*:
+          #   - *tag* (+string+) A <a data-item-id=""> tag found in the content
+          #   - *links* (+Array+) The collection of links from an element's 'links' JSON node, converted to Kontent::Ai::Delivery::Resolvers::ContentLink objects
+          #
+          # * *Returns*:
+          #   - +string+ The <a data-item-id=""> tag with an HREF generated by the +provide_url+ method
+          def resolve_tag(tag, links)
+            matches = links.select { |link| link.id == tag['data-item-id'].to_s }
+            url = provide_url matches, tag['data-item-id']
+            tag['href'] = url
+            tag
+          end
+
+          # Uses the +resolve_link+ method to generate a URL for a ContentLink
+          # object, or +resolve_404+ if the content item was not present in the
+          # response.
+          #
+          # * *Args*:
+          #   - *matches* (+Array+) The ContentLink objects with an ID matching a particular <a data-item-id=""> tag
+          #   - *id* (+string+) The ID of the <a data-item-id=""> tag being resolved
+          #
+          # * *Returns*:
+          #   - +string+ A url to the item or 404 page
+          def provide_url(matches, id)
+            if matches.empty?
+              if @not_found_handler.nil?
+                resolve_404 id
+              else
+                @not_found_handler.call id
+              end
+            else
+              if @found_handler.nil?
+                resolve_link matches[0]
+              else
+                @found_handler.call matches[0]
+              end
+            end
+          end
+        end
+
+        # Model for links from the JSON response
+        class ContentLink
+          attr_accessor :code_name, :type, :url_slug, :id
+
+          # Constructor.
+          #
+          # * *Args*:
+          #   - *link* (+JSON+) One link from an element's 'links' JSON node
+          def initialize(link)
+            self.id = link[0]
+            self.code_name = link[1]['codename']
+            self.type = link[1]['type']
+            self.url_slug = link[1]['url_slug']
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/resolvers/inline_content_item_resolver.rb

@@ -0,0 +1,75 @@
+require 'nokogiri'
+
+module Kontent
+  module Ai
+    module Delivery
+      module Resolvers
+        # Locates <object data-type="item"> tags in content and calls a user-defined
+        # method to supply the output for the content item.
+        # See https://github.com/kontent-ai/delivery-sdk-ruby#resolving-inline-content
+        class InlineContentItemResolver
+          def initialize(callback = nil)
+            @callback = callback
+          end
+
+          # Resolves all inline content items in the content.
+          #
+          # * *Args*:
+          #   - *content* (+string+) The string value stored in the element
+          #   - *inline_items* (+Array+) ContentItems referenced by the content from the 'modular_content' JSON node
+          #
+          # * *Returns*:
+          #   - +string+ The original content passed, with all <object data-type="item"> replaced with custom output
+          def resolve(content, inline_items)
+            doc = Nokogiri::HTML.parse(content).xpath('//body')
+            tags = doc.xpath('//object[@type="application/kenticocloud"][@data-type="item"]')
+            tags.each do |tag|
+              output = resolve_tag tag, inline_items
+              el = doc.at_xpath(
+                '//object[@type="application/kenticocloud"][@data-type="item"][@data-codename=$value]',
+                nil,
+                value: tag['data-codename']
+              )
+              el.swap(output) unless output.nil?
+            end
+            doc.inner_html
+          end
+
+          private
+
+          # Accepts a tag found in the content and tries to locate matching
+          # ContentItem from JSON response.
+          #
+          # * *Args*:
+          #   - *tag* (+string+) A <object data-type="item"> tag found in the content
+          #   - *inline_items* (+Array+) ContentItems referenced by the content from the 'modular_content' JSON node
+          #
+          # * *Returns*:
+          #   - +string+ The custom output generated by the +provide_output+ method
+          def resolve_tag(tag, inline_items)
+            matches = inline_items.select { |item| item.system.codename == tag['data-codename'].to_s }
+            provide_output matches
+          end
+
+          # Generates custom output for a content item using the +resolve_item+
+          # method.
+          #
+          # * *Args*:
+          #   - *matches* (+Array+) The ContentItems from the 'modular_content' JSON node which match the code name of a particular <object data-type="item"> tag
+          #
+          # * *Returns*:
+          #   - +string+ The custom output generated by the +resolve_item+ method
+          def provide_output(matches)
+            if !matches.empty?
+              if @callback.nil?
+                resolve_item matches[0]
+              else
+                @callback.call matches[0]
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/resolvers/linked_item_resolver.rb

@@ -0,0 +1,43 @@
+module Kontent
+  module Ai
+    module Delivery
+      module Resolvers
+        # Resolves a content item by its codename. It contains the modular content
+        # of item/items response.
+        class LinkedItemResolver
+          def initialize(modular_content, content_link_url_resolver, inline_content_item_resolver)
+            @modular_content = modular_content
+            @content_link_url_resolver = content_link_url_resolver
+            @inline_content_item_resolver = inline_content_item_resolver
+            @resolved_items = {}
+          end
+
+          # Resolves a content item. If the link for a codename was resolved
+          # before, it returns the same instance of ContentItem.
+          #
+          # * *Args*:
+          #   - *codename* (+string+) Codename of the content item
+          #
+          # * *Return*:
+          #   - Kontent::Ai::Delivery::ContentItem
+          def resolve(codename)
+            @resolved_items[codename] ||= resolve_item(codename)
+          end
+
+          private
+
+          def resolve_item(codename)
+            item = @modular_content.values.find { |i| i['system']['codename'] == codename }
+            unless item.nil?
+              return ContentItem.new(JSON.parse(JSON.generate(item)),
+                                     @content_link_url_resolver,
+                                     @inline_content_item_resolver,
+                                     self)
+            end
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/responses/delivery_element_response.rb

@@ -0,0 +1,34 @@
+require 'delivery/responses/response_base'
+
+module Kontent
+  module Ai
+    module Delivery
+      module Responses
+        # The response of a successful query of a content type's element
+        # See https://github.com/kontent-ai/delivery-sdk-ruby#retrieving-content-type-elements
+        class DeliveryElementResponse < ResponseBase
+          # An element's definition from a
+          # Kontent::Ai::Delivery::DeliveryClient.element call
+          #
+          # * *Returns*:
+          #   - +OpenStruct+ The element of a content item
+          def element
+            @element unless @element.nil?
+            @element = JSON.parse(
+              JSON.generate(@response),
+              object_class: OpenStruct
+            )
+          end
+
+          def initialize(headers, body)
+            @response = JSON.parse(body)
+            super 200,
+              "Success, '#{element.codename}' returned",
+              headers,
+              JSON.generate(@response)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/responses/delivery_item_listing_response.rb

@@ -0,0 +1,54 @@
+require 'delivery/models/content_item'
+require 'delivery/models/pagination'
+require 'delivery/responses/response_base'
+
+module Kontent
+  module Ai
+    module Delivery
+      module Responses
+        # The response of a successful query for content items.
+        # See https://github.com/kontent-ai/delivery-sdk-ruby#listing-items
+        class DeliveryItemListingResponse < ResponseBase
+          # Parses the 'pagination' JSON node of the response.
+          #
+          # * *Returns*:
+          #   - Kontent::Ai::Delivery::Pagination
+          def pagination
+            @pagination unless @pagination.nil?
+            @pagination = Pagination.new @response['pagination']
+          end
+
+          # A collection of Kontent::Ai::Delivery::ContentItem objects from
+          # a Kontent::Ai::Delivery::DeliveryClient.items call.
+          #
+          # * *Returns*:
+          #   - +Array+ One or more Kontent::Ai::Delivery::ContentItem objects
+          def items
+            @items unless @items.nil?
+            linked_items_resolver = Kontent::Ai::Delivery::Resolvers::LinkedItemResolver.new @response['modular_content'], @content_link_url_resolver, @inline_content_item_resolver
+            items = []
+            @response['items'].each do |n|
+              items << Kontent::Ai::Delivery::ContentItem.new(
+                n,
+                @content_link_url_resolver,
+                @inline_content_item_resolver,
+                linked_items_resolver
+              )
+            end
+            @items = items
+          end
+
+          def initialize(headers, body, query)
+            @response = JSON.parse(body)
+            @content_link_url_resolver = query.content_link_url_resolver
+            @inline_content_item_resolver = query.inline_content_item_resolver
+            super 200,
+              "Success, #{items.length} items returned",
+              headers,
+              JSON.generate(@response)
+          end
+        end
+      end
+    end
+  end
+end