contentful-management 0.8.0 → 0.9.0

data/lib/contentful/management/client.rb

@@ -12,24 +12,37 @@ require 'logger'
 
 module Contentful
   module Management
+    # Client for interacting with the Contentful Management API
+    # @see _ https://www.contentful.com/developers/docs/references/content-management-api/
     class Client
       extend Contentful::Management::HTTPClient
 
       attr_reader :access_token, :configuration, :logger
       attr_accessor :organization_id, :version, :zero_length, :content_type_id, :dynamic_entry_cache
 
+      # Default configuration for Contentful::Management::Client
       DEFAULT_CONFIGURATION = {
-          api_url: 'api.contentful.com',
-          api_version: '1',
-          secure: true,
-          default_locale: 'en-US',
-          gzip_encoded: false,
-          logger: false,
-          log_level: Logger::INFO,
-          raise_errors: false,
-          dynamic_entries: []
+        api_url: 'api.contentful.com',
+        api_version: '1',
+        secure: true,
+        default_locale: 'en-US',
+        gzip_encoded: false,
+        logger: false,
+        log_level: Logger::INFO,
+        raise_errors: false,
+        dynamic_entries: []
       }
 
+      # @param [String] access_token
+      # @param [Hash] configuration
+      # @option configuration [String] :api_url
+      # @option configuration [String] :api_version
+      # @option configuration [String] :default_locale
+      # @option configuration [Boolean] :gzip_encoded
+      # @option configuration [false, ::Logger] :logger
+      # @option configuration [::Logger::DEBUG, ::Logger::INFO, ::Logger::WARN, ::Logger::ERROR] :log_level
+      # @option configuration [Boolean] :raise_errors
+      # @option configuration [::Array<String>] :dynamic_entries
       def initialize(access_token = nil, configuration = {})
         @configuration = default_configuration.merge(configuration)
         setup_logger
@@ -39,18 +52,21 @@ module Contentful
         update_all_dynamic_entry_cache!
       end
 
+      # @private
       def setup_logger
         @logger = configuration[:logger]
         logger.level = configuration[:log_level] if logger
       end
 
+      # @private
       def update_all_dynamic_entry_cache!
-        if !configuration[:dynamic_entries].empty?
-          spaces = configuration[:dynamic_entries].map { |space_id| ::Contentful::Management::Space.find(space_id) }
-          update_dynamic_entry_cache_for_spaces!(spaces)
-        end
+        return if configuration[:dynamic_entries].empty?
+
+        spaces = configuration[:dynamic_entries].map { |space_id| ::Contentful::Management::Space.find(space_id) }
+        update_dynamic_entry_cache_for_spaces!(spaces)
       end
 
+      # @private
       def update_dynamic_entry_cache_for_spaces!(spaces)
         spaces.each do |space|
           update_dynamic_entry_cache_for_space!(space)
@@ -59,36 +75,43 @@ module Contentful
 
       # Use this method together with the client's :dynamic_entries configuration.
       # See README for details.
+      # @private
       def update_dynamic_entry_cache_for_space!(space)
         update_dynamic_entry_cache!(space.content_types.all)
       end
 
+      # @private
       def update_dynamic_entry_cache!(content_types)
         content_types.each do |ct|
           @dynamic_entry_cache[ct.id.to_sym] = DynamicEntry.create(ct)
         end
       end
 
+      # @private
       def api_version
         configuration[:api_version]
       end
 
+      # @private
       def gzip_encoded
         configuration[:gzip_encoded]
       end
 
+      # @private
       def default_configuration
         DEFAULT_CONFIGURATION.dup
       end
 
+      # @private
       def register_dynamic_entry(key, klass)
         @dynamic_entry_cache[key.to_sym] = klass
       end
 
+      # @private
       def execute_request(request)
         request_url = request.url
         url = request.absolute? ? request_url : base_url + request_url
-        logger.info(request: {url: url, query: request.query, header: request_headers}) if logger
+        logger.info(request: { url: url, query: request.query, header: request_headers }) if logger
         raw_response = yield(url)
         logger.debug(response: raw_response) if logger
         clear_headers
@@ -97,81 +120,98 @@ module Contentful
         result
       end
 
+      # @private
       def clear_headers
         self.content_type_id = nil
         self.version = nil
         self.organization_id = nil
       end
 
+      # @private
       def delete(request)
         execute_request(request) do |url|
           self.class.delete_http(url, {}, request_headers)
         end
       end
 
+      # @private
       def get(request)
         execute_request(request) do |url|
           self.class.get_http(url, request.query, request_headers)
         end
       end
 
+      # @private
       def post(request)
         execute_request(request) do |url|
           self.class.post_http(url, request.query, request_headers)
         end
       end
 
+      # @private
       def put(request)
         execute_request(request) do |url|
           self.class.put_http(url, request.query, request_headers)
         end
       end
 
+      # @private
       def base_url
-        "#{ protocol }://#{ configuration[:api_url]}/spaces"
+        "#{protocol}://#{configuration[:api_url]}/spaces"
       end
 
+      # @private
       def default_locale
         configuration[:default_locale]
       end
 
+      # @private
       def protocol
         configuration[:secure] ? 'https' : 'http'
       end
 
+      # @private
       def authentication_header
-        Hash['Authorization', "Bearer #{ access_token }"]
+        Hash['Authorization', "Bearer #{access_token}"]
       end
 
+      # @private
       def api_version_header
-        Hash['Content-Type', "application/vnd.contentful.management.v#{ api_version }+json"]
+        Hash['Content-Type', "application/vnd.contentful.management.v#{api_version}+json"]
       end
 
+      # @private
       def user_agent
-        Hash['User-Agent', "RubyContentfulManagementGem/#{ Contentful::Management::VERSION }"]
+        Hash['User-Agent', "RubyContentfulManagementGem/#{Contentful::Management::VERSION}"]
       end
 
+      # @private
       def organization_header(organization_id)
         Hash['X-Contentful-Organization', organization_id]
       end
 
+      # @private
       def version_header(version)
         Hash['X-Contentful-Version', version]
       end
 
+      # @private
       def content_type_header(content_type_id)
         Hash['X-Contentful-Content-Type', content_type_id]
       end
 
+      # @private
       def zero_length_header
         Hash['Content-Length', 0]
       end
 
+      # @private
       def accept_encoding_header(encoding)
         Hash['Accept-Encoding', encoding]
       end
 
-      # XXX: headers should be supplied differently, maybe through the request object.
+      # @todo headers should be supplied differently, maybe through the request object.
+      # @private
       def request_headers
         headers = {}
         headers.merge! user_agent
@@ -185,6 +225,7 @@ module Contentful
         headers
       end
 
+      # @private
       def self.shared_instance
         Thread.current[:client]
       end

data/lib/contentful/management/content_type.rb

@@ -7,19 +7,20 @@ require_relative 'support'
 module Contentful
   module Management
     # Resource class for ContentType.
-    # https://www.contentful.com/developers/documentation/content-management-api/#resources-content-types
+    # @see _ https://www.contentful.com/developers/documentation/content-management-api/#resources-content-types
     class ContentType
+      # Shortcuts for Contentful Field Types
       FIELD_TYPES = [
-          SYMBOL = 'Symbol',
-          TEXT = 'Text',
-          INTEGER = 'Integer',
-          FLOAT = 'Number',
-          DATE = 'Date',
-          BOOLEAN = 'Boolean',
-          LINK = 'Link',
-          ARRAY = 'Array',
-          OBJECT = 'Object',
-          LOCATION = 'Location'
+        SYMBOL = 'Symbol',
+        TEXT = 'Text',
+        INTEGER = 'Integer',
+        FLOAT = 'Number',
+        DATE = 'Date',
+        BOOLEAN = 'Boolean',
+        LINK = 'Link',
+        ARRAY = 'Array',
+        OBJECT = 'Object',
+        LOCATION = 'Location'
       ]
 
       include Contentful::Management::Resource
@@ -32,12 +33,20 @@ module Contentful
       property :displayField, :string
 
       # Gets a collection of content types.
-      # Takes an id of space and an optional hash of query options
-      # Returns a Contentful::Management::Array of Contentful::Management::ContentType.
+      #
+      # @param [String] space_id
+      # @param [Hash] query Search Options
+      # @see _ For complete option list: http://docs.contentfulcda.apiary.io/#reference/search-parameters
+      # @option query [String] 'sys.id' Content Type ID
+      # @option query [String] :name Kind of Content Type
+      # @option query [Integer] :limit
+      # @option query [Integer] :skip
+      #
+      # @return [Contentful::Management::Array<Contentful::Management::ContentType>]
       def self.all(space_id, query = {})
         request = Request.new(
-            "/#{ space_id }/content_types",
-            query
+          "/#{space_id}/content_types",
+          query
         )
         response = request.get
         result = ResourceBuilder.new(response, {}, {})
@@ -46,11 +55,37 @@ module Contentful
         content_types
       end
 
-      # Gets a specific entry.
-      # Takes an id of space and content type.
-      # Returns a Contentful::Management::ContentType.
+      # Gets a collection of published content types.
+      #
+      # @param [String] space_id
+      # @param [Hash] query Search Options
+      # @see _ For complete option list: http://docs.contentfulcda.apiary.io/#reference/search-parameters
+      # @option query [String] 'sys.id' Content Type ID
+      # @option query [String] :name Kind of Content Type
+      # @option query [Integer] :limit
+      # @option query [Integer] :skip
+      #
+      # @return [Contentful::Management::Array<Contentful::Management::ContentType>]
+      def self.all_published(space_id, query = {})
+        request = Request.new(
+          "/#{space_id}/public/content_types",
+          query
+        )
+        response = request.get
+        result = ResourceBuilder.new(response, {}, {})
+        content_types = result.run
+        client.update_dynamic_entry_cache!(content_types)
+        content_types
+      end
+
+      # Gets a specific content type.
+      #
+      # @param [String] space_id
+      # @param [String] content_type_id
+      #
+      # @return [Contentful::Management::ContentType]
       def self.find(space_id, content_type_id)
-        request = Request.new("/#{ space_id }/content_types/#{ content_type_id }")
+        request = Request.new("/#{space_id}/content_types/#{content_type_id}")
         response = request.get
         result = ResourceBuilder.new(response, {}, {})
         content_type = result.run
@@ -59,9 +94,10 @@ module Contentful
       end
 
       # Destroys a content type.
-      # Returns true if succeed.
+      #
+      # @return [true, Contentful::Management::Error] success
       def destroy
-        request = Request.new("/#{ space.id }/content_types/#{ id }")
+        request = Request.new("/#{space.id}/content_types/#{id}")
         response = request.delete
         if response.status == :no_content
           return true
@@ -75,10 +111,10 @@ module Contentful
       # Returns a Contentful::Management::ContentType.
       def activate
         request = Request.new(
-            "/#{ space.id }/content_types/#{ id }/published",
-            {},
-            id = nil,
-            version: sys[:version]
+          "/#{space.id}/content_types/#{id}/published",
+          {},
+          nil,
+          version: sys[:version]
         )
         response = request.put
         result = ResourceBuilder.new(response, {}, {}).run
@@ -87,34 +123,42 @@ module Contentful
 
       # Deactivates a content type.
       # Only content type that has no entries can be deactivated.
-      # Returns a Contentful::Management::ContentType.
+      #
+      # @return [Contentful::Management::ContentType]
       def deactivate
-        request = Request.new("/#{ space.id }/content_types/#{ id }/published")
+        request = Request.new("/#{space.id}/content_types/#{id}/published")
         response = request.delete
         result = ResourceBuilder.new(response, {}, {}).run
         refresh_data(result)
       end
 
       # Checks if a content type is active.
-      # Returns true if active.
+      #
+      # @return [Boolean]
       def active?
         sys[:publishedAt] ? true : false
       end
 
       # Creates a content type.
-      # Takes an id of space and hash with attributes.
-      # Returns a Contentful::Management::ContentType.
+      #
+      # @param [String] space_id
+      # @param [Hash] attributes
+      # @option attributes [String] :id
+      # @option attributes [String] :name
+      # @option attributes [::Array<Contentful::Management::Field>] :fields
+      #
+      # @return [Contentful::Management::ContentType]
       def self.create(space_id, attributes)
         fields = fields_to_nested_properties_hash(attributes[:fields] || [])
 
         params = attributes.clone
         params[:fields] = fields
         params.delete(:id)
-        params = params.delete_if { |k, v| v.nil? }
+        params = params.delete_if { |_, v| v.nil? }
 
         request = Request.new(
-            "/#{ space_id }/content_types/#{ attributes[:id]}",
-            params
+          "/#{space_id}/content_types/#{attributes[:id]}",
+          params
         )
         response = attributes[:id].nil? ? request.post : request.put
         result = ResourceBuilder.new(response, {}, {}).run
@@ -122,6 +166,7 @@ module Contentful
         result
       end
 
+      # @private
       def display_field_value(attributes)
         if attributes[:displayField].nil? && (display_field.nil? || display_field.empty?)
           nil
@@ -131,8 +176,13 @@ module Contentful
       end
 
       # Updates a content type.
-      # Takes a hash with attributes.
-      # Returns a Contentful::Management::ContentType.
+      #
+      # @param [Hash] attributes
+      # @option attributes [String] :id
+      # @option attributes [String] :name
+      # @option attributes [::Array<Contentful::Management::Field>] :fields
+      #
+      # @return [Contentful::Management::ContentType]
       def update(attributes)
         parameters = {}
         parameters.merge!(displayField: display_field_value(attributes))
@@ -140,12 +190,12 @@ module Contentful
         parameters.merge!(description: (attributes[:description] || description))
         parameters.merge!(fields: self.class.fields_to_nested_properties_hash(attributes[:fields] || fields))
 
-        parameters = parameters.delete_if { |k, v| v.nil? }
+        parameters = parameters.delete_if { |_, v| v.nil? }
         request = Request.new(
-            "/#{ space.id }/content_types/#{ id }",
-            parameters,
-            id = nil,
-            version: sys[:version]
+          "/#{space.id}/content_types/#{id}",
+          parameters,
+          nil,
+          version: sys[:version]
         )
         response = request.put
         result = ResourceBuilder.new(response, {}, {}).run
@@ -153,7 +203,9 @@ module Contentful
       end
 
       # If a content type is a new object gets created in the Contentful, otherwise the existing entry gets updated.
-      # See README for details.
+      # @see _ README for details.
+      #
+      # @return [Contentful::Management::ContentType]
       def save
         if id
           update(@properties)
@@ -164,6 +216,7 @@ module Contentful
       end
 
       # This method merges existing fields with new one, when adding, creating or updating new fields.
+      # @private
       def merged_fields(new_field)
         field_ids = []
         merged_fields = fields.each_with_object([]) do |field, fields|
@@ -175,17 +228,18 @@ module Contentful
         merged_fields
       end
 
+      # @private
       alias_method :orig_fields, :fields
 
       # Use this method only in the context of content type.
       # Allows you to add and create a field with specified attributes or destroy by pass field id.
-      # Returns a Contentful::Management::ContentType.
-      # See README for details.
+      # @see _ README for details.
+      #
+      # @return [Contentful::Management::ContentType]
       def fields
         fields = orig_fields
 
         fields.instance_exec(self) do |content_type|
-
           fields.define_singleton_method(:add) do |field|
             content_type.update(fields: content_type.merged_fields(field))
           end
@@ -204,7 +258,6 @@ module Contentful
             fields = content_type.fields.select { |field| field.id != id }
             content_type.update(fields: fields)
           end
-
         end
 
         fields
@@ -212,14 +265,16 @@ module Contentful
 
       # Use this method only in the context of content type.
       # Allows you to create an entry.
-      # Returns a Contentful::Management::Entry.
-      # See README for details.
+      # @see _ README for details.
+      #
+      # @private
+      #
+      # @return [Contentful::Management::ContentTypeEntryMethodsFactory]
       def entries
         Contentful::Management::ContentTypeEntryMethodsFactory.new(self)
       end
 
-      private
-
+      # @private
       def self.fields_to_nested_properties_hash(fields)
         fields.map do |field|
           field.properties.replace(field.properties_to_hash)