kontent-ai-delivery 3.0.0

data/lib/delivery/builders/image_transformation_builder.rb

@@ -0,0 +1,272 @@
+require 'delivery/query_parameters/query_string'
+
+module Kontent
+  module Ai
+    module Delivery
+      module Builders
+        # Provides methods for manipulating the URL of an asset to adjust the image's
+        # size, cropping behavior, background color, output format, and quality.
+        #
+        # See https://kontent.ai/learn/reference/image-transformation/ and
+        # https://github.com/kontent-ai/delivery-sdk-ruby#image-transformation.
+        class ImageTransformationBuilder
+          FIT_MODE_CLIP = 'clip'.freeze
+          FIT_MODE_SCALE = 'scale'.freeze
+          FIT_MODE_CROP = 'crop'.freeze
+          FORMAT_GIF = 'gif'.freeze
+          FORMAT_PNG = 'png'.freeze
+          FORMAT_PNG8 = 'png8'.freeze
+          FORMAT_JPG = 'jpg'.freeze
+          FORMAT_PJPG = 'pjpg'.freeze
+          FORMAT_WEBP = 'webp'.freeze
+
+          class << self
+            def transform(url)
+              AssetURL.new url
+            end
+          end
+        end
+
+        class AssetURL
+          INVALID_PARAMS = 'One or more of the parameters is invalid. '\
+          'See https://kontent.ai/learn/reference/image-transformation/#a-focal-point-crop'\
+          'for more information.'.freeze
+          ONE_TO_100 = 'Quality parameter must be between 1 and 100.'.freeze
+          BOOLEAN_PARAM = 'The parameter must be a boolean, 0, or 1.'.freeze
+
+          # Constructor. Generally, you obtain an +AssetURL+ object by calling
+          # Kontent::Ai::Delivery::Builders::ImageTransformationBuilder.transform
+          # instead of using this constructor.
+          def initialize(url)
+            @url = url
+            @query_string = Kontent::Ai::Delivery::QueryParameters::QueryString.new
+          end
+
+          # Applies all transformation options to the asset URL.
+          #
+          # * *Returns*:
+          #   - +string+ The full URL to the asset with all query string parameters set
+          def url
+            @url + @query_string.to_s
+          end
+
+          # Sets the width of the image
+          #
+          # * *Args*:
+          #   - *width*
+          #     - +integer+ Width in pixels, between 1 and 8192.
+          #     - +float+ Width in percentage, between 0 and 1.
+          #
+          # * *Returns*:
+          #   - +self+
+          def with_width(width)
+            @query_string.set_param 'w', width
+            self
+          end
+
+          # Sets the height of the image
+          #
+          # * *Args*:
+          #   - *height*
+          #     - +integer+ Height in pixels, between 1 and 8192.
+          #     - +float+ Height in percentage, between 0 and 1.
+          #
+          # * *Returns* :
+          #   - +self+
+          def with_height(height)
+            @query_string.set_param 'h', height
+            self
+          end
+
+          # Sets the device pixel ratio. Either width or height
+          # (or both) must be set.
+          #
+          # * *Args*:
+          #   - *dpr* (+float+) Pixel ratio between 0 and 5.
+          #
+          # * *Returns*:
+          #   - +self+
+          def with_pixel_ratio(dpr)
+            @query_string.set_param 'dpr', dpr
+            self
+          end
+
+          # Defines how the image is constrained while resizing. Either width
+          # or height (or both) must be set.
+          #
+          # * *Args*:
+          #   - *fit* (+string+) Use constants from Kontent::Ai::Delivery::Builders::ImageTransformationBuilder
+          #
+          # * *Returns*:
+          #   - +self+
+          def with_fit_mode(fit)
+            @query_string.set_param 'fit', fit
+            self
+          end
+
+          # Selects a region of the image to perform transformations on.
+          # Setting this will remove focal point cropping from the image,
+          # as the two options are incompatible.
+          #
+          # * *Args*:
+          #   - *x*
+          #     - +integer+ The left border of the rect in pixels
+          #     - +float+ The left border of the rect as a percentage between 0 and 1
+          #   - *y*
+          #     - +integer+ The top border of the rect in pixels
+          #     - +float+ The top border of the rect as a percentage between 0 and 1
+          #   - *width*
+          #     - +integer+ The width of the rect in pixels
+          #     - +float+ The width of the rect as a percentage between 0 and 1
+          #   - *height*
+          #     - +integer+ The height of the rect in pixels
+          #     - +float+ The height of the rect as a percentage between 0 and 1
+          #
+          # * *Returns*:
+          #   - +self+
+          def with_rect(x, y, width, height)
+            @query_string.remove_param 'fp-x'
+            @query_string.remove_param 'fp-y'
+            @query_string.remove_param 'fp-z'
+            @query_string.remove_param 'fit'
+            @query_string.remove_param 'crop'
+            @query_string.set_param 'rect', "#{x},#{y},#{width},#{height}"
+            self
+          end
+
+          # Sets the point of interest when cropping the image.
+          # Setting this will remove the source rectangle region,
+          # as the two options are incompatible. It also automatically sets the
+          # crop to "focalpoint" and fit to "crop"
+          #
+          # * *Args*:
+          #   - *x* (+float+) Percentage of the image's width between 0 and 1
+          #   - *y* (+float+) Percentage of the image's height between 0 and 1
+          #   - *z* (+integer+) Amount of zoom to apply. A value of 1 is the default zoom, and each step represents 100% additional zoom.
+          #
+          # * *Returns*:
+          #   - +self+
+          def with_focal_point(x, y, z)
+            raise ArgumentError, INVALID_PARAMS unless valid_dims?(x, y, z)
+
+            @query_string.remove_param 'rect'
+            @query_string.set_param 'fp-x', x
+            @query_string.set_param 'fp-y', y
+            @query_string.set_param 'fp-z', z
+            @query_string.set_param 'fit', ImageTransformationBuilder::FIT_MODE_CROP
+            @query_string.set_param 'crop', 'focalpoint'
+            self
+          end
+
+          # Sets the background color of any transparent areas of the image.
+          #
+          # * *Args*:
+          #   - *color* (+string+) A valid 3, 4, 6, or 8 digit hexadecimal color, without the # symbol
+          #
+          # * *Returns*:
+          #   - +self+
+          def with_background_color(color)
+            @query_string.set_param 'bg', color
+            self
+          end
+
+          # Sets the output format of the request for the image.
+          #
+          # * *Args*:
+          #   - *format* (+string+) Use constants from Kontent::Ai::Delivery::Builders::ImageTransformationBuilder
+          #
+          # * *Returns*:
+          #   - +self+
+          def with_output_format(format)
+            @query_string.set_param 'fm', format
+            self
+          end
+
+          # Configure the amount of compression for lossy file formats. Lower quality
+          # images will have a smaller file size. Only affects *jpg*, *pjpg*, and
+          # *webp* files.
+          #
+          # When no quality is specified for an image transformation, the default
+          # value of 85 is used.
+          #
+          # * *Args*:
+          #   - *quality* (+integer+) The quality of the image between 1 and 100
+          #
+          # * *Returns*:
+          #   - +self+
+          #
+          # * *Raises*:
+          #   - +ArgumentError+ if +quality+ is not between 1 and 100 inclusive
+          def with_quality(quality)
+            raise ArgumentError, ONE_TO_100 unless quality.to_i >= 1 && quality.to_i <= 100
+
+            @query_string.set_param 'q', quality
+            self
+          end
+
+          # Sets the lossless parameter. If +true+, automatically sets the format
+          # to WebP.
+          #
+          # * *Args*:
+          #   - *lossless*
+          #     - +integer+ Either 1 or 0
+          #     - +bool+ Either +true+ or +false+
+          #     - +string+ Either 'true' or 'false'
+          #
+          # * *Returns*:
+          #   - +self+
+          #
+          # * *Raises*:
+          #   - +ArgumentError+ if +lossless+ cannot be parsed as a boolean
+          def with_lossless(lossless)
+            lossless = lossless.to_s.downcase
+            raise ArgumentError, BOOLEAN_PARAM unless bool? lossless
+
+            @query_string.set_param 'lossless', lossless
+            @query_string.set_param 'fm', Kontent::Ai::Delivery::Builders::ImageTransformationBuilder::FORMAT_WEBP if %w[true 1].include? lossless
+            self
+          end
+
+          # Enables or disables automatic format selection. If enabled, it will
+          # override the format parameter and deliver WebP instead. If the browser
+          # does not support WebP, the value of the format parameter will be used.
+          #
+          # * *Args*:
+          #   - *auto*
+          #     - +integer+ Either 1 or 0
+          #     - +bool+ Either +true+ or +false+
+          #     - +string+ Either 'true' or 'false'
+          #
+          # * *Returns*:
+          #   - +self+
+          #
+          # * *Raises*:
+          #   - +ArgumentError+ if +auto+ cannot be parsed as a boolean
+          def with_auto_format_selection(auto)
+            auto = auto.to_s.downcase
+            raise ArgumentError, BOOLEAN_PARAM unless bool? auto
+
+            if %w[true 1].include? auto
+              @query_string.set_param 'auto', 'format'
+            else
+              @query_string.remove_param 'auto'
+            end
+            self
+          end
+
+          private
+
+          def valid_dims?(x, y, z)
+            (x.to_f >= 0.0 && x.to_f <= 1.0) &&
+              (y.to_f >= 0.0 && y.to_f <= 1.0) &&
+              (z.to_i >= 1)
+          end
+
+          def bool?(value)
+            %w[true false 0 1].include? value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/builders/url_builder.rb

@@ -0,0 +1,123 @@
+module Kontent
+  module Ai
+    module Delivery
+      module Builders
+        # Internal class which generates the URL required for Delivery REST API
+        class UrlBuilder
+          URL_TEMPLATE_BASE = 'https://deliver.kontent.ai/%s'.freeze
+          URL_TEMPLATE_PREVIEW = 'https://preview-deliver.kontent.ai/%s'.freeze
+          URL_TEMPLATE_ITEM = '/items/%s'.freeze
+          URL_TEMPLATE_ITEMS = '/items'.freeze
+          URL_TEMPLATE_TYPE = '/types/%s'.freeze
+          URL_TEMPLATE_TYPES = '/types'.freeze
+          URL_TEMPLATE_ELEMENTS = '/types/%s/elements/%s'.freeze
+          URL_TEMPLATE_TAXONOMY = '/taxonomies/%s'.freeze
+          URL_TEMPLATE_TAXONOMIES = '/taxonomies'.freeze
+          URL_TEMPLATE_ITEMS_FEED = '/items-feed'.freeze
+          URL_TEMPLATE_LANGUAGES = '/languages'.freeze
+
+          URL_MAX_LENGTH = 65_519
+          MSG_LONG_QUERY = 'The request url is too long. Split your query into multiple calls.'.freeze
+
+          class << self
+            # Returns the proper domain for the request along with the
+            # query string parameters configured by the +DeliveryQuery+.
+            #
+            # * *Args*:
+            #   - *query* ( Kontent::Ai::Delivery::DeliveryQuery )
+            #
+            # * *Returns*:
+            #   - +string+ The full URL for a Delivery request
+            def provide_url(query)
+              url = provide_base_url(query)
+              url += provide_path_part(query)
+
+              if query.query_string.empty?
+                url
+              else
+                url + query.query_string.to_s
+              end
+            end
+
+            # Checks whether the provided URL is too long and raises an error if so.
+            #
+            # * *Args*:
+            #   - *url* (+string+) A full Delivery URL
+            #
+            # * *Raises*:
+            #   - +UriFormatException+ if the URL is 65,519 characters or more
+            def validate_url(url)
+              raise UriFormatException, MSG_LONG_QUERY if url.length > URL_MAX_LENGTH
+            end
+
+            private
+
+            # Returns relative path part of URL depending on query type.
+            #
+            # * *Args*:
+            #   - *query* ( Kontent::Ai::Delivery::DeliveryQuery )
+            #
+            # * *Returns*:
+            #   - +string+ The URL path part (without protocol or domain)
+            def provide_path_part(query)
+              case query.query_type
+              when Kontent::Ai::Delivery::QUERY_TYPE_ITEMS
+                provide_item query
+              when Kontent::Ai::Delivery::QUERY_TYPE_TYPES
+                provide_type query
+              when Kontent::Ai::Delivery::QUERY_TYPE_TAXONOMIES
+                provide_taxonomy query
+              when Kontent::Ai::Delivery::QUERY_TYPE_LANGUAGES
+                URL_TEMPLATE_LANGUAGES
+              when Kontent::Ai::Delivery::QUERY_TYPE_ELEMENT
+                format(URL_TEMPLATE_ELEMENTS, query.content_type, query.code_name)
+              when Kontent::Ai::Delivery::QUERY_TYPE_ITEMS_FEED
+                URL_TEMPLATE_ITEMS_FEED
+              end
+            end
+
+            def provide_item(query)
+              if query.code_name.nil?
+                URL_TEMPLATE_ITEMS
+              else
+                format(URL_TEMPLATE_ITEM, query.code_name)
+              end
+            end
+
+            def provide_taxonomy(query)
+              if query.code_name.nil?
+                URL_TEMPLATE_TAXONOMIES
+              else
+                format(URL_TEMPLATE_TAXONOMY, query.code_name)
+              end
+            end
+
+            def provide_type(query)
+              if query.code_name.nil?
+                URL_TEMPLATE_TYPES
+              else
+                format(URL_TEMPLATE_TYPE, query.code_name)
+              end
+            end
+
+            # Returns the protocol and domain with project ID. Domain changes
+            # according to the query's +use_preview+ attribute.
+            #
+            # * *Args*:
+            #   - *query* ( Kontent::Ai::Delivery::DeliveryQuery )
+            #
+            # * *Returns*:
+            #   - +string+ The URL with the project ID
+            def provide_base_url(query)
+              if query.use_preview
+                format(URL_TEMPLATE_PREVIEW, query.project_id)
+              else
+                format(URL_TEMPLATE_BASE, query.project_id)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/delivery/client/delivery_client.rb

@@ -0,0 +1,184 @@
+require 'delivery/client/delivery_query'
+require 'delivery/responses/delivery_item_listing_response'
+require 'delivery/responses/delivery_item_response'
+require 'json'
+
+module Kontent
+  module Ai
+    module Delivery
+      QUERY_TYPE_TYPES = 'QUERY_TYPE_TYPES'.freeze
+      QUERY_TYPE_ITEMS = 'QUERY_TYPE_ITEMS'.freeze
+      QUERY_TYPE_TAXONOMIES = 'QUERY_TYPE_TAXONOMIES'.freeze
+      QUERY_TYPE_ELEMENT = 'QUERY_TYPE_ELEMENT'.freeze
+      QUERY_TYPE_ITEMS_FEED = 'QUERY_TYPE_ITEMS_FEED'.freeze
+      QUERY_TYPE_LANGUAGES = 'QUERY_TYPE_LANGUAGES'.freeze
+
+      # Executes requests against the Kontent.ai Delivery API.
+      class DeliveryClient
+        attr_accessor :use_preview
+
+        # Constructor. Accepts a hash with the options for client.
+        #
+        # * *Args*:
+        #   - *config* (+Hash+) May contain the following keys:
+        #     - project_id (+string+) _required_
+        #     - preview_key (+string+)
+        #     - secure_key (+string+)
+        #     - content_link_url_resolver ( Kontent::Ai::Delivery::Resolvers::ContentLinkResolver )
+        #     - inline_content_item_resolver ( Kontent::Ai::Delivery::Resolvers::InlineContentItemResolver )
+        #     - with_retry_policy (+bool+)
+        def initialize(config)
+          @project_id = config.fetch(:project_id)
+          @preview_key = config.fetch(:preview_key, nil)
+          @secure_key = config.fetch(:secure_key, nil)
+          @content_link_url_resolver = config.fetch(:content_link_url_resolver, nil)
+          @inline_content_item_resolver = config.fetch(:inline_content_item_resolver, nil)
+          @with_retry_policy = config.fetch(:with_retry_policy, true)
+          self.use_preview = !@preview_key.nil?
+        end
+
+        # Return all content types of the project
+        #
+        # * *Returns*:
+        #   - Kontent::Ai::Delivery::DeliveryQuery
+        def types
+          DeliveryQuery.new project_id: @project_id,
+                            secure_key: @secure_key,
+                            query_type: QUERY_TYPE_TYPES,
+                            with_retry_policy: @with_retry_policy
+        end
+
+        # Return a single content type of the project
+        #
+        # * *Args*:
+        #   - *code_name* (+string+) Code name of the desired content type
+        #
+        # * *Returns*:
+        #   - Kontent::Ai::Delivery::DeliveryQuery
+        def type(code_name)
+          DeliveryQuery.new project_id: @project_id,
+                            secure_key: @secure_key,
+                            code_name: code_name,
+                            query_type: QUERY_TYPE_TYPES,
+                            with_retry_policy: @with_retry_policy
+        end
+
+        # Return a paginated feed of all content items of the project
+        #
+        # * *Args*:
+        #   - *query_parameters* (+Array+) _optional_ One or more Kontent::Ai::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
+        #
+        # * *Returns*:
+        #   - Kontent::Ai::Delivery::DeliveryQuery
+        def items_feed(query_parameters = [])
+          q = DeliveryQuery.new project_id: @project_id,
+                                secure_key: @secure_key,
+                                qp: query_parameters,
+                                content_link_url_resolver: @content_link_url_resolver,
+                                inline_content_item_resolver: @inline_content_item_resolver,
+                                query_type: QUERY_TYPE_ITEMS_FEED,
+                                with_retry_policy: @with_retry_policy
+          q.use_preview = use_preview
+          q.preview_key = @preview_key
+          q
+        end
+
+        # Return all content items of the project
+        #
+        # * *Args*:
+        #   - *query_parameters* (+Array+) _optional_ One or more Kontent::Ai::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
+        #
+        # * *Returns*:
+        #   - Kontent::Ai::Delivery::DeliveryQuery
+        def items(query_parameters = [])
+          q = DeliveryQuery.new project_id: @project_id,
+                                secure_key: @secure_key,
+                                qp: query_parameters,
+                                content_link_url_resolver: @content_link_url_resolver,
+                                inline_content_item_resolver: @inline_content_item_resolver,
+                                query_type: QUERY_TYPE_ITEMS,
+                                with_retry_policy: @with_retry_policy
+          q.use_preview = use_preview
+          q.preview_key = @preview_key
+          q
+        end
+
+        # Return a single content item of the project
+        #
+        # * *Args*:
+        #   - *code_name* (+string+) The code name of the desired content item
+        #   - *query_parameters* (+Array+) _optional_ One or more Kontent::Ai::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
+        #
+        # * *Returns*:
+        #   - Kontent::Ai::Delivery::DeliveryQuery
+        def item(code_name, query_parameters = [])
+          q = DeliveryQuery.new project_id: @project_id,
+                                secure_key: @secure_key,
+                                code_name: code_name,
+                                qp: query_parameters,
+                                content_link_url_resolver: @content_link_url_resolver,
+                                inline_content_item_resolver: @inline_content_item_resolver,
+                                query_type: QUERY_TYPE_ITEMS,
+                                with_retry_policy: @with_retry_policy
+          q.use_preview = use_preview
+          q.preview_key = @preview_key
+          q
+        end
+
+        # Return all taxonomy groups of the project
+        #
+        # * *Args*:
+        #   - *query_parameters* (+Array+) _optional_ One or more Kontent::Ai::Delivery::QueryParameters::Filter objects. A single object will automatically be converted into an Array.
+        #
+        # * *Returns*:
+        #   - Kontent::Ai::Delivery::DeliveryQuery
+        def taxonomies(query_parameters = [])
+          DeliveryQuery.new project_id: @project_id,
+                            secure_key: @secure_key,
+                            qp: query_parameters,
+                            query_type: QUERY_TYPE_TAXONOMIES,
+                            with_retry_policy: @with_retry_policy
+        end
+
+        # Return a single taxonomy group of the project
+        #
+        # * *Args*:
+        #   - *code_name* (+string+) The code name of the desired taxonomy group
+        #
+        # * *Returns*:
+        #   - Kontent::Ai::Delivery::DeliveryQuery
+        def taxonomy(code_name)
+          DeliveryQuery.new project_id: @project_id,
+                            secure_key: @secure_key,
+                            code_name: code_name,
+                            query_type: QUERY_TYPE_TAXONOMIES,
+                            with_retry_policy: @with_retry_policy
+        end
+
+        # Return a single element of a content type
+        #
+        # * *Args*:
+        #   - *content_type* (+string+) The code name of the content type containing the element
+        #   - *element* (+string+) The code name of the desired element
+        #
+        # * *Returns*:
+        #   - Kontent::Ai::Delivery::DeliveryQuery
+        def element(content_type, element)
+          DeliveryQuery.new project_id: @project_id,
+                            secure_key: @secure_key,
+                            code_name: element,
+                            content_type: content_type,
+                            query_type: QUERY_TYPE_ELEMENT,
+                            with_retry_policy: @with_retry_policy
+        end
+
+        def languages
+          DeliveryQuery.new project_id: @project_id,
+                            secure_key: @secure_key,
+                            query_type: QUERY_TYPE_LANGUAGES,
+                            with_retry_policy: @with_retry_policy
+        end
+      end
+    end
+  end
+end