contentful 0.1.0

data/lib/contentful/client.rb

@@ -0,0 +1,193 @@
+require_relative 'request'
+require_relative 'response'
+require_relative 'resource_builder'
+require 'http'
+
+module Contentful
+  # The client object is initialized with a space and a key and then used
+  # for querying resources from this space.
+  # See README for details
+  class Client
+    DEFAULT_CONFIGURATION = {
+      secure: true,
+      raise_errors: true,
+      dynamic_entries: :manual,
+      api_url: 'cdn.contentful.com',
+      api_version: 1,
+      authentication_mechanism: :header,
+      resource_builder: ResourceBuilder,
+      resource_mapping: {},
+      raw_mode: false,
+    }
+
+    attr_reader :configuration, :dynamic_entry_cache
+
+
+    # Wraps the actual HTTP request
+    def self.get_http(url, query, headers = {})
+      HTTP[headers].get(url, params: query)
+    end
+
+    def initialize(given_configuration = {})
+      @configuration = default_configuration.merge(given_configuration)
+      normalize_configuration!
+      validate_configuration!
+
+      if configuration[:dynamic_entries] == :auto
+        update_dynamic_entry_cache!
+      else
+        @dynamic_entry_cache = {}
+      end
+    end
+
+    # Returns the default configuration
+    def default_configuration
+      DEFAULT_CONFIGURATION
+    end
+
+    # Gets the client's space
+    # Takes an optional hash of query options
+    # Returns a Contentful::Space
+    def space(query = {})
+      Request.new(self, '', query).get
+    end
+
+    # Gets a specific content type
+    # Takes an id and an optional hash of query options
+    # Returns a Contentful::ContentType
+    def content_type(id, query = {})
+      Request.new(self, '/content_types', query, id).get
+    end
+
+    # Gets a collection of content types
+    # Takes an optional hash of query options
+    # Returns a Contentful::Array of Contentful::ContentType
+    def content_types(query = {})
+      Request.new(self, '/content_types', query).get
+    end
+
+    # Gets a specific entry
+    # Takes an id and an optional hash of query options
+    # Returns a Contentful::Entry
+    def entry(id, query = {})
+      Request.new(self, '/entries', query, id).get
+    end
+
+    # Gets a collection of entries
+    # Takes an optional hash of query options
+    # Returns a Contentful::Array of Contentful::Entry
+    def entries(query = {})
+      Request.new(self, '/entries', query).get
+    end
+
+    # Gets a specific asset
+    # Takes an id and an optional hash of query options
+    # Returns a Contentful::Asset
+    def asset(id, query = {})
+      Request.new(self, '/assets', query, id).get
+    end
+
+    # Gets a collection of assets
+    # Takes an optional hash of query options
+    # Returns a Contentful::Array of Contentful::Asset
+    def assets(query = {})
+      Request.new(self, '/assets', query).get
+    end
+
+    # Returns the base url for all of the client's requests
+    def base_url
+      "http#{configuration[:secure] ? 's' : ''}://#{configuration[:api_url]}/spaces/#{configuration[:space]}"
+    end
+
+    # Returns the headers used for the HTTP requests
+    def request_headers
+      headers = { "User-Agent" => "RubyContentfulGem/#{Contentful::VERSION}" }
+      headers["Authorization"] = "Bearer #{configuration[:access_token]}" if configuration[:authentication_mechanism] == :header
+      headers["Content-Type"]  = "application/vnd.contentful.delivery.v#{configuration[:api_version].to_i}+json" if configuration[:api_version]
+
+      headers
+    end
+
+    # Patches a query hash with the client configurations for queries
+    def request_query(query)
+      if configuration[:authentication_mechanism] == :query_string
+        query["access_token"] = configuration[:access_token]
+      end
+
+      query
+    end
+
+    # Get a Contentful::Request object
+    # Set second parameter to false to deactivate Resource building and
+    # return Response objects instead
+    def get(request, build_resource = true)
+      response = Response.new(
+        self.class.get_http(
+          base_url + request.url,
+          request_query(request.query),
+          request_headers,
+        ), request
+      )
+
+      return response if !build_resource || configuration[:raw_mode]
+
+      result = configuration[:resource_builder].new(self, response, configuration[:resource_mapping]).run
+      raise result if result.is_a?(Error) && configuration[:raise_errors]
+      result
+    end
+
+    # Use this method together with the client's :dynamic_entries configuration.
+    # See README for details.
+    def update_dynamic_entry_cache!
+      @dynamic_entry_cache = Hash[
+        content_types(limit: 0).map{ |ct|
+          [
+            ct.id.to_sym,
+            DynamicEntry.create(ct),
+          ]
+        }
+      ]
+    end
+
+    # Use this method to manually register a dynamic entry
+    # See examples/dynamic_entries.rb
+    def register_dynamic_entry(key, klass)
+      @dynamic_entry_cache[key.to_sym] = klass
+    end
+
+
+    private
+
+    def normalize_configuration!
+      [:space, :access_token, :api_url].each{ |s| configuration[s] = configuration[s].to_s }
+      configuration[:authentication_mechanism] = configuration[:authentication_mechanism].to_sym
+    end
+
+    def validate_configuration!
+      if configuration[:space].empty?
+        raise ArgumentError, "You will need to initialize a client with a :space"
+      end
+
+      if configuration[:access_token].empty?
+        raise ArgumentError, "You will need to initialize a client with an :access_token"
+      end
+
+      if configuration[:api_url].empty?
+        raise ArgumentError, "The client configuration needs to contain an :api_url"
+      end
+
+      unless configuration[:api_version].to_i >= 0
+        raise ArgumentError, "The :api_version must be a positive number or nil"
+      end
+
+      unless [:header, :query_string].include? configuration[:authentication_mechanism]
+        raise ArgumentError, "The authentication mechanism must be :header or :query_string"
+      end
+
+      unless [:auto, :manual].include? configuration[:dynamic_entries]
+        raise ArgumentError, "The :dynamic_entries mode must be :auto or :manual"
+      end
+    end
+  end
+end
+

data/lib/contentful/content_type.rb

@@ -0,0 +1,16 @@
+require_relative 'resource'
+require_relative 'field'
+
+module Contentful
+  # Resource Class for Content Types
+  # https://www.contentful.com/developers/documentation/content-delivery-api/#content-types
+  class ContentType
+    include Contentful::Resource
+    include Contentful::Resource::SystemProperties
+
+    property :name, :string
+    property :description, :string
+    property :fields, Field
+    property :displayField, :string
+  end
+end

data/lib/contentful/dynamic_entry.rb

@@ -0,0 +1,54 @@
+require_relative 'resource'
+require_relative 'resource/fields'
+require_relative 'location'
+
+module Contentful
+  class DynamicEntry < Entry
+    KNOWN_TYPES = {
+      'String'   => :string,
+      'Text'     => :string,
+      'Symbol'   => :string,
+      'Integer'  => :integer,
+      'Float'    => :float,
+      'Boolean'  => :boolean,
+      'Date'     => :date,
+      'Location' => Location,
+    }
+
+    def self.create(content_type)
+      unless content_type.is_a? ContentType
+        content_type = ContentType.new(content_type)
+      end
+
+      fields_coercions = Hash[
+        content_type.fields.map{ |field|
+          [field.id.to_sym, KNOWN_TYPES[field.type]]
+        }
+      ]
+
+      Class.new DynamicEntry do
+        content_type.fields.each{ |f|
+          define_method Support.snakify(f.id).to_sym do
+            fields[f.id.to_sym]
+          end
+        }
+
+        define_singleton_method :fields_coercions do
+          fields_coercions
+        end
+
+        define_singleton_method :content_type do
+          content_type
+        end
+
+        define_singleton_method :to_s do
+          "Contentful::DynamicEntry[#{content_type.id}]"
+        end
+
+        define_singleton_method :inspect do
+          "Contentful::DynamicEntry[#{content_type.id}]"
+        end
+      end
+    end
+  end
+end

data/lib/contentful/entry.rb

@@ -0,0 +1,12 @@
+require_relative 'resource'
+require_relative 'resource/fields'
+
+module Contentful
+  # Resource class for Entry.
+  # https://www.contentful.com/developers/documentation/content-delivery-api/#entries
+  class Entry
+    include Contentful::Resource
+    include Contentful::Resource::SystemProperties
+    include Contentful::Resource::Fields
+  end
+end

data/lib/contentful/error.rb

@@ -0,0 +1,52 @@
+module Contentful
+  # All errors raised by the contentful gem are either instances of Contentful::Error
+  # or inherit from Contentful::Error
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(response)
+      @response = response
+      super @response.error_message
+    end
+
+    # Shortcut for creating specialized error classes
+    # USAGE rescue Contentful::Error[404]
+    def self.[](no)
+      case no
+      when 404
+        NotFound
+      when 400
+        BadRequest
+      when 403
+        AccessDenied
+      when 401
+        Unauthorized
+      when 500
+        ServerError
+      else
+        Error
+      end
+    end
+  end
+
+  # 404
+  class NotFound < Error; end
+
+  # 400
+  class BadRequest < Error; end
+
+  # 403
+  class AccessDenied < Error; end
+
+  # 401
+  class Unauthorized < Error; end
+
+  # 500
+  class ServerError < Error; end
+
+  # Raised when response is no valid json
+  class UnparsableJson < Error; end
+
+  # Raised when response is not parsable as a Contentful::Resource
+  class UnparsableResource < Error; end
+end

data/lib/contentful/field.rb

@@ -0,0 +1,16 @@
+require_relative 'resource'
+
+module Contentful
+  # A ContentType's field schema
+  # See https://www.contentful.com/developers/documentation/content-management-api/#resources-content-types-fields
+  class Field
+    include Contentful::Resource
+
+    property :id, :string
+    property :name, :string
+    property :type, :string
+    property :items, Field
+    property :required, :boolean
+    property :localized, :boolean
+  end
+end

data/lib/contentful/file.rb

@@ -0,0 +1,13 @@
+require_relative 'resource'
+
+module Contentful
+  # An Assets's file info
+  class File
+    include Contentful::Resource
+
+    property :fileName, :string
+    property :contentType, :string
+    property :details
+    property :url, :string
+  end
+end

data/lib/contentful/link.rb

@@ -0,0 +1,20 @@
+require_relative 'resource'
+
+module Contentful
+  # Resource Class for Links
+  # https://www.contentful.com/developers/documentation/content-delivery-api/#links
+  class Link
+    include Contentful::Resource
+    include Contentful::Resource::SystemProperties
+
+    # Queries contentful for the Resource the Link is refering to
+    # Takes an optional query hash
+    def resolve(query = {})
+      id_and_query = [(id unless link_type == "Space")].compact + [query]
+      client.public_send(
+        Contentful::Support.snakify(link_type).to_sym,
+        *id_and_query
+      )
+    end
+  end
+end

data/lib/contentful/locale.rb

@@ -0,0 +1,12 @@
+require_relative 'resource'
+
+module Contentful
+  # A Locale definition as included in Space
+  # Read more about Localization at https://www.contentful.com/developers/documentation/content-delivery-api/#i18n
+  class Locale
+    include Contentful::Resource
+
+    property :code, :string
+    property :name, :string
+  end
+end

data/lib/contentful/location.rb

@@ -0,0 +1,12 @@
+require_relative 'resource'
+
+module Contentful
+  # Location Field Type
+  # You can directly query for them: https://www.contentful.com/developers/documentation/content-delivery-api/#search-filter-geo
+  class Location
+    include Contentful::Resource
+
+    property :lat, :float
+    property :lon, :float
+  end
+end

data/lib/contentful/request.rb

@@ -0,0 +1,37 @@
+module Contentful
+  # This object represents a request that is to be made. It gets initialized by the client
+  # with domain specific logic. The client later uses the Request's #url and #query methods
+  # to execute the HTTP request.
+  class Request
+    attr_reader :client, :type, :query, :id
+
+    def initialize(client, endpoint, query = {}, id = nil)
+      @client = client
+      @endpoint = endpoint
+      @query = !query || query.empty? ? nil : Support.symbolize_keys(query)
+
+      if id
+        @type = :single
+        @id = URI.escape(id)
+      else
+        @type = :multi
+        @id = nil
+      end
+    end
+
+    # Returns the final URL, relative to a contentful space
+    def url
+      "#{@endpoint}#{ @type == :single ? "/#{id}" : '' }"
+    end
+
+    # Delegates the actual HTTP work to the client
+    def get
+      client.get(self)
+    end
+
+    # Returns a new Request object with the same data
+    def copy
+      Marshal.load(Marshal.dump(self))
+    end
+  end
+end