contentful_lite 1.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 02c47f18feb382f97913063f3447bd7c9e00f40d7dc684a571f2c4cf9f400a80
+  data.tar.gz: 82a09e5c38cc7acbe580e28f524f6697d383ac117dae9cc67a0b5baf4e586618
+SHA512:
+  metadata.gz: 57ac0c6defaba6ef173434ecbc496179496038559eddd75332ab5900981ba923447aa79fb23fd69a8f873a026793a042a730da839ac4111c67197fcbdb33fa04
+  data.tar.gz: 8d2f8a50516e8bedb28e08c16e290c36c3111c67fc74b4ef45d4c30cea45469a0dd4a8f5385fd0b2e5ab4dc90d01f64270e72b12b35b693b69b14c020ea9d10d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 JUUL Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,257 @@
+# contentful_lite
+
+![Rspec](https://github.com/JuulLabs-OSS/contentful_lite/workflows/Rspec/badge.svg?branch=master&event=push)
+
+> Ruby SDK gem for retrieving content from Contentful Content Delivery API and Content Preview API. A lighter replacement for the official contentful gem.
+
+### But why?
+We've been using the official contentful gem for a while and we discovered it was causing a big memory leak. Among other issues, the main problem was that on the official gem the serialization of entries for cache stores a lot of extra information that we didn't require, causing to spend more cache memory unnecessarily. So we decided to build a custom lite gem providing support only for the features we were using.
+
+## Features
+- Retrieve entries and assets from CDA and CPA
+- Localization support
+- Modeling of Content Types into Ruby classes
+- Cache serialization
+- Content validations using ActiveModel::Validations
+- Retrieve data from any environment
+- Pagination data
+
+## Getting Started
+
+#### Installation
+Add to your Gemfile:
+
+`gem 'contentful_lite', git: "https://github.com/JuulLabs-OSS/contentful_lite.git"`
+
+#### Use it!
+```ruby
+  require 'contentful_lite'
+
+  # First create the client by providing  your space id and access token.
+  # You can also add environment: 'any_env' or preview: true if you prefer to use CPA
+  client = ContentfulLite::Client.new(space_id: 'cfexampleapi', access_token: 'b4c0n73n7fu1')
+  # Then request the entries
+  client.entries
+```
+
+## Creating your model classes with macros
+
+This gem was created for being able to subclass the `ContentfulLite::Entry` and provide custom methods for each of the content models that you create on your contentful space.
+
+This customization is really easy to implement. An example of a complete model may look like this:
+
+```ruby
+  class ContentPage < ContentfulLite::Entry
+    content_type_id 'content_page'
+
+    field_reader :title, :open_graph_image
+    field_reader :layout, default: 'simple'
+    field_reader :sections, default: []
+
+    validates :title, presence: true
+    validates_included_entry :sections, array: true
+    validates_included_asset :open_graph_image, type: 'image'
+  end
+```
+
+### Simple step by step explanation
+
+1. Create a class and inherit from `ContentfulLite::Entry`
+2. Call `content_type_id` to set the mapping to the right contentful content model.
+3. Call `field_reader` macro to setup your field accessors.
+4. Define your validations
+
+### Reference for field accessors macros
+
+- #### field_reader
+
+  This macro define accessors methods for one or many fields.
+
+  **Parameters:**
+
+  - `*attrs` A symbol or array of symbols with the fields name you want to define.
+  - `default: nil` The default value in case there is no value for that field.
+  - `localizable: false` A boolean to indicate if this field is marked as localizable on contentful. If true, calling `#field_name(locale: custom)` will try to retrieve the value for that locale. If false, the same call will ignore the provided locale and instead use the main locale for the entry.
+
+### Reference for validations macros
+
+Validations are implemented using ActiveModel::Validations so all the active model validation methods can be used, but you can also call our custom validation macros for contentful entries.
+
+- #### validates\_included\_entry
+
+  Adds a validation for attributes with referenced entries.
+
+  **Parameters:**
+
+  - `*attr_names` A symbol or array of symbols with the fields name you want to include in this validation.
+  - `allow_blank: false` Optional boolean to determine if the validation should pass when the field is blank.
+  - `array: false` Optional boolean to determine if the field should be a single entry or an array of entries.
+  - `allowed_models: nil` Optional array of ruby subclasses of `ContentfulLite::Entry` with the allowed models to be referenced by this field. If not provided, any class will be allowed.
+
+- #### validates\_included\_asset
+
+  Adds a validation for attributes with referenced assets.
+
+  **Parameters:**
+
+  - `*attr_names` A symbol or array of symbols with the fields name you want to include in this validation.
+  - `allow_blank: false` Boolean to determine if the validation should pass when the field is blank.
+  - `array: false` Boolean to determine if the field should be a single asset or an array of assets.
+  - `type: nil` String for validate it's appearance inside the file's content type. If not provided, the content type check will be omitted.
+
+## Public Methods Reference
+
+### ContentfulLite::Client
+- #### #initialize `client = ContentfulLite::Client.new`
+
+  Builds the client for being able to retrieve data.
+
+   **Parameters:**
+   - `space_id:` Mandatory, you need to include the space_id you want to retrieve content from
+   - `access_token:` Mandatory, provide an access token for that space. You can read more about access tokens on [Contentful Documentation for CDA Authentication](https://www.contentful.com/developers/docs/references/content-delivery-api/#/introduction/authentication)
+   - `environment: nil` Optional. If you want to retrieve the content from an environment that is not the default on contentful, you can include the environment name here.
+   - `preview: false` Optional. True for using Content Preview API, otherwise it will use Content Delivery API.
+
+
+- #### #entries `client.entries(query = {})`
+
+  Searches for all the entries that fulfills the query conditions and returns an array (`ContentfulLite::EntriesArray`) with all the retrieved entries, using the right subclass of `ContentfulLite::Entry` (according to the entry mapping) for each of the entries.
+
+  **Parameters:**
+  - `query: {}` Optional, a hash representing any parameter you want to include in your CDA/CPA query. Read about search parameters on the [Contentful Documentation for Search Parameters](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters)
+
+
+- #### #entry `client.entry(id, query = {})`
+  Retrieves a single entry by id and returns an object of the right subclass of `ContentfulLite::Entry` according to the entry mapping.
+
+  **Parameters:**
+  - `id` Mandatory, the id for the entry you want to retrieve.
+  - `query = {}` Optional, a hash representing any parameter you want to include in your CDA/CPA query. Read about search parameters on the [Contentful Documentation for Search Parameters](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters). Note that this API call doesn't allow the `include` parameter.
+
+
+- #### #assets `client.assets(query = {})`
+
+  Searches for all the assets that fulfills the query conditions and returns an array (`ContentfulLite::AssetsArray`) with all the requested assets
+
+  **Parameters:**
+  - `query: {}` Optional, a hash representing any parameter you want to include in your CDA/CPA query. Read about search parameters on the [Contentful Documentation for Search Parameters](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters)
+
+- #### #asset `client.asset(id, query = {})`
+
+  Retrieves a single asset by id and returns a `ContentfulLite::Asset`
+
+  **Parameters:**
+  - `id` Mandatory, the id for the asset you want to retrieve.
+  - `query = {}` Optional, a hash representing any parameter you want to include in your CDA/CPA query. Read about search parameters on the [Contentful Documentation for Search Parameters](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/search-parameters).
+
+
+- #### #build\_resource `client.build_resource(raw)`
+
+  Used for webhooks, it receives a raw body from the webhook callback and returns the right object according to the `sys.type`.
+
+  **Parameters:**
+  - `raw` Mandatory, the raw JSON received from the webhook callback.
+
+### ContentfulLite::Entry
+- #### #contentful\_link `entry.contentful_link`
+
+  Returns the link to edit the entry on the contentful webapp.
+
+- #### #fields `entry.fields(locale: nil)`
+
+  Provided a hash with all the fields on the specified locale
+
+  **Parameters:**
+  - `locale: nil` Optional, the locale code for the fields you want to retrieve. Defaults to first received locale
+
+- #### #valid? `entry.valid?(locale: nil)`
+
+  Executes the validations for the specified locale.
+
+  **Parameters:**
+  - `locale: nil` Optional, the locale code you want to validate. Defaults to first received locale
+
+    Reference to #valid? [Active Model Documentation](https://api.rubyonrails.org/v5.2.3/classes/ActiveModel/Validations.html) for more information about this method.
+
+- #### #errors `entry.errors(locale: nil)`
+
+  Provides a ActiveModel::Errors with all the errors for the specified locale. You need to call it after `#valid?`
+
+  **Parameters:**
+  - `locale: nil` Optional, the locale code for the errors you want to retrieve. Defaults to first received locale
+
+    Reference to #errors [Active Model Documentation](https://api.rubyonrails.org/v5.2.3/classes/ActiveModel/Validations.html) for more information about this method.
+
+
+- #### #valid\_for\_all\_locales? `entry.valid_for_all_locales?`
+
+  Runs `#valid?` for each locale in the entry.
+
+- #### #errors\_for\_all\_locales `entry.errors_for_all_locales`
+
+  Returns an array of `locale => ActiveModel::Errors`
+
+- #### fields accessors `entry.field_name(locale: nil)`
+
+  Field accessors are defined using the `field_reader` macro. They receive and optional locale as parameter and returns the value for that field in the provided locale. Using the macro as `field_reader :content_field` will provide a `entry.content_field(locale: nil)` method.
+
+  **Parameters:**
+  - `locale: nil` Optional, the locale code for the field you want to retrieve. Defaults to first received locale
+
+- #### sys accessors
+
+  ```
+  #id, #created_at, #updated_at, #locale,
+  #revision, #space_id, #environment_id,
+  #retrieved_at, #locales
+  ```
+  Provides access to the system data for the entry
+
+
+### ContentfulLite::Asset
+
+- #### #contentful\_link `asset.contentful_link`
+
+  Returns the link to edit the asset on the contentful webapp.
+
+- #### sys accessors
+
+  ```
+  #id, #created_at, #updated_at, #locale,
+  #revision, #space_id, #environment_id,
+  #retrieved_at, #locales
+  ```
+  Provides access to the system data for the entry
+
+- #### asset accessors
+  ```
+  #title(locale: nil), #description(locale: nil),
+  #file_name(locale: nil), #content_type(locale: nil)
+  #url(locale: nil), file_details(locale: nil)
+  ```
+  Provides access to the asset data in the requested locale.
+
+  **Parameters:**
+  - `locale: nil` Optional, the locale code for the fields you want to retrieve. Defaults to first received locale
+
+### ContentfulLite::AssetsArray and ContentfulLite::EntriesArray
+
+These classes inherits all methods from ruby Array class, but also implements the support for pagination data.
+
+- #### #total `array.total`
+
+  Returns the total number of resources (entries or assets) for the request that created the array.
+
+- #### #skip `array.skip`
+
+  Returns the number of skipped resources (entries or assets) for the request that created the array.
+
+- #### #limit `array.limit`
+
+  Returns the maximum number of resources returned (entries or assets) for the request that created the array.
+
+## Development
+
+### Git Hooks
+
+  To Alias git hooks locally run `git config core.hooksPath git_hooks` inside the project.

data/lib/contentful_lite/asset.rb

@@ -0,0 +1,30 @@
+require 'http'
+
+module ContentfulLite
+  class Asset
+    include CommonData
+
+    # Gets the URL to view/edit the entry on Contentful webapp
+    # @return [String]
+    def contentful_link
+      "https://app.contentful.com/spaces/#{space_id}/assets/#{id}"
+    end
+
+    # @api private
+    # @!macro [attach] asset_attribute
+    #   Returns the $1 attribute of the Contentful Asset
+    def self.asset_attribute(key, path, default: nil)
+      define_method(key) do |locale: nil|
+        path.inject(fields(locale: locale)) { |hash, path_section| hash.nil? ? nil : hash[path_section] } || default
+      end
+    end
+    private_class_method :asset_attribute
+
+    asset_attribute :title, ['title']
+    asset_attribute :description, ['description'], default: ''
+    asset_attribute :file_name, ['file', 'fileName']
+    asset_attribute :content_type, ['file', 'contentType']
+    asset_attribute :url, ['file', 'url']
+    asset_attribute :file_details, ['file', 'details']
+  end
+end

data/lib/contentful_lite/assets_array.rb

@@ -0,0 +1,12 @@
+module ContentfulLite
+  class AssetsArray < BaseArray
+    # @param raw [Hash] raw response from Contentful API
+    # @api private
+    def initialize(raw)
+      super(raw)
+
+      # Create the array of asset objects
+      @items.collect! { |item| ContentfulLite::Asset.new(item) }
+    end
+  end
+end

data/lib/contentful_lite/base_array.rb

@@ -0,0 +1,29 @@
+module ContentfulLite
+  class BaseArray < Delegator
+    # The total number of items in the result
+    attr_reader :total
+    # The skip parameter sent to Contentful API for getting this result
+    attr_reader :skip
+    # The maximum number of resources returned per request
+    attr_reader :limit
+
+    # @param raw [Hash] raw response from Contentful API
+    # @api private
+    def initialize(raw)
+      @total = raw['total']
+      @skip = raw['skip']
+      @limit = raw['limit']
+      @items = raw.fetch('items', [])
+    end
+
+    # @api private
+    def __getobj__
+      @items
+    end
+
+    # @api private
+    def __setobj__(value)
+      @items = value
+    end
+  end
+end

data/lib/contentful_lite/client.rb

@@ -0,0 +1,110 @@
+require 'http'
+
+module ContentfulLite
+  class Client
+    class RequestError < StandardError
+      attr_reader :response, :body
+
+      def initialize(response, body)
+        @response = response
+        @body = body
+        super(body['sys'] && body['sys']['type'] == 'Error' ? "#{body['sys']['id']}: #{body['message']}" : "Invalid Contentful Response: #{body}")
+      end
+    end
+    class NotFoundError < RequestError; end
+
+    attr_reader :space_id, :environment, :preview
+
+    # Creates the Contentful Client
+    # @param space_id [String] the Contentful Space Id you want to connect to.
+    # @param access_token [String] The secret access token to access the api
+    # @param environment [String, nil] To allow querying to a non-master environment
+    # @param preview [Boolean] True if you want to get draft entries
+    def initialize(space_id:, access_token:, environment: nil, preview: false)
+      @space_id = space_id
+      @environment = environment
+      @preview = preview
+      @access_token = access_token
+    end
+
+    # Gets an array of entries from Contentful API
+    # @param query [Hash] any query params accepted by Contentful API
+    # @return [ContentfulLite::EntriesArray]
+    def entries(query = {})
+      ContentfulLite::EntriesArray.new(request(:entries, query))
+    end
+
+    # Gets a single entry from Contentful API
+    # @param id [String] Unique id of the Contentful entry
+    # @param query [Hash] any query params accepted by Contentful API
+    # @return [ContentfulLite::Entry]
+    def entry(id, query = {})
+      parse_entry request("entries/#{id}", query)
+    end
+
+    # Gets a single asset from Contentful API
+    # @param id [String] Unique id of the Contentful asset
+    # @param query [Hash] any query params accepted by Contentful API
+    # @return [ContentfulLite::Asset]
+    def asset(id, query = {})
+      ContentfulLite::Asset.new(request("assets/#{id}", query))
+    end
+
+    # Gets an array of assets from Contentful API
+    # @param query [Hash] any query params accepted by Contentful API
+    # @return [ContentfulLite::AssetsArray]
+    def assets(query = {})
+      ContentfulLite::AssetsArray.new(request(:assets, query))
+    end
+
+    # Build an entry resource from a raw Contentful API response
+    # @param raw [Hash] a JSON parsed response from Contentful API
+    # @return [ContentfulLite::Entry,ContentfulLite::Asset,ContentfulLite::DeletedEntry]
+    def build_resource(raw)
+      case raw['sys']['type']
+      when 'Entry'
+        parse_entry(raw)
+      when 'Asset'
+        ContentfulLite::Asset.new(raw)
+      when 'DeletedEntry'
+        ContentfulLite::DeletedEntry.new(raw)
+      end
+    end
+
+    private
+
+    def parse_entry(hash)
+      klass = ContentfulLite::Entry.get_class(hash['sys']['contentType']['sys']['id'])
+      klass.new(hash)
+    end
+
+    def create_url(endpoint)
+      "https://#{preview ? 'preview' : 'cdn'}.contentful.com/spaces/#{space_id}/" +
+        ( environment.nil? ? '' : "environments/#{environment}/" ) +
+        endpoint.to_s
+    end
+
+    def request(endpoint, parameters)
+      parameters.transform_keys!(&:to_s)
+      parameters.transform_values! { |value| value.is_a?(::Array) ? value.join(',') : value }
+      response = HTTP[request_headers].get(create_url(endpoint), params: parameters)
+      body = response.to_s
+      body = Zlib::GzipReader.new(StringIO.new(body)).read if response.headers['Content-Encoding'].eql?('gzip')
+      JSON.parse(body).tap do |parsed|
+        raise error_class(response.status).new(response, parsed) if response.status != 200
+      end
+    end
+
+    def request_headers
+      {
+        'Authorization' => "Bearer #{@access_token}",
+        'Content-Type' => 'application/vnd.contentful.delivery.v1+json',
+        'Accept-Encoding' => 'gzip'
+      }
+    end
+
+    def error_class(status)
+      status == 404 ? NotFoundError : RequestError
+    end
+  end
+end

data/lib/contentful_lite/common_data.rb

@@ -0,0 +1,95 @@
+require "active_support/core_ext/object/json"
+require "active_support/core_ext/hash/keys"
+
+module ContentfulLite
+  # Parses data common to all Contentful resources.
+  module CommonData
+    attr_reader :id, :created_at, :updated_at, :default_locale, :revision, :space_id, :environment_id, :retrieved_at, :locales, :localized_fields, :sys
+
+    # @param raw [Hash] raw response from Contentful API
+    # @api private
+    def initialize(raw)
+      @sys = raw['sys']
+      @id = sys['id']
+      @created_at = DateTime.parse sys['createdAt']
+      @updated_at = DateTime.parse sys['updatedAt']
+      @locale = sys['locale']
+      @revision = sys['revision']
+      @space_id = sys['space']['sys']['id']
+      @environment_id = sys['environment']['sys']['id']
+      @retrieved_at = DateTime.now
+
+      if locale
+        @locales = [locale]
+        @localized_fields = { locale => raw['fields'] }
+      else
+        @locales = raw.fetch('fields', {}).values.collect_concat(&:keys).uniq
+        @localized_fields = @locales.each_with_object({}) do |locale, hash|
+          hash[locale] = raw['fields'].transform_values { |value| value[locale] }
+        end
+      end
+
+      @default_locale = @locales.first
+    end
+
+    # Provides access to the locale being used to read fields
+    def locale
+      @locale || @default_locale
+    end
+
+    # Sets the locale that will be used to read fields
+    # @param value [String] the locale code
+    # @raise [StandardError] 'Invalid Locale' for locales not included on the API response
+    def locale=(value)
+      raise 'Invalid Locale' unless value.in?(locales)
+
+      @locale = value
+    end
+
+    # Returns a hash with field => value format using specified locale
+    # @param locale [String, nil] the locale that will be used for reading the fields. Defaults to {#locale}
+    # @return [Hash]
+    def fields(locale: nil)
+      @localized_fields.fetch(locale || self.locale, {})
+    end
+
+    # Executes a block with {#locale} set to the received locale. Then sets it back
+    # to current locale.
+    # @param locale [String] the locale to run the block with
+    # @yield
+    def with_locale(locale)
+      old_locale = @locale
+      @locale = locale unless locale.nil?
+      begin
+        yield
+      ensure
+        @locale = old_locale
+      end
+    end
+
+    # Gets a ContentfulLite::Link to the entry
+    # @return [ContentfulLite::Link] a link to this entry
+    def to_link
+      ContentfulLite::Link.new(self)
+    end
+
+    # Provided for compatibility with Rails JSON serializer
+    # @param serialized_ids [Array<String>] Ids already serialized, required for possible mutual references
+    # @param options [Hash] Serialization options, only provided for compatibility
+    # @return [Hash] a Hash representation of the link, to be formated as JSON
+    def as_json(serialized_ids: [], **options)
+      return to_link.as_json if serialized_ids.include?(id)
+
+      {
+        "sys" => sys,
+        "fields" => fields.transform_values do |value|
+          if value.respond_to?(:as_json)
+            value.as_json(serialized_ids: serialized_ids + [id], **options)
+          else
+            value
+          end
+        end
+      }
+    end
+  end
+end

data/lib/contentful_lite/deleted_entry.rb

@@ -0,0 +1,10 @@
+module ContentfulLite
+  class DeletedEntry < Entry
+    # Not implemented, provided for compatibility reasons
+    # @raise NotImplementedError
+    # @api private
+    def contentful_link
+      raise NotImplementedError.new('contentful_link is not available for deleted entries')
+    end
+  end
+end

data/lib/contentful_lite/entries_array.rb

@@ -0,0 +1,62 @@
+module ContentfulLite
+  class EntriesArray < BaseArray
+    # @param raw [Hash] raw response from Contentful API
+    # @api private
+    def initialize(raw)
+      super(raw)
+
+      # Collect arrays of missing (unresolvable) links
+      @errors = raw.fetch('errors', []).collect! { |error| error.fetch('details', {}) }.each_with_object({}) do |error_detail, hash|
+        type = error_detail['linkType'].downcase.to_sym
+        hash[type] ||= []
+        hash[type] << error_detail['id']
+      end
+
+      # Create the array of asset objects
+      @assets = hash_by_id(
+        raw.fetch('includes', {}).fetch('Asset', [])
+      ).transform_values! { |asset| ContentfulLite::Asset.new(asset) }
+
+      # Now parse the entries, this is the tricky part
+      @entries = {}
+      @raw_entries = hash_by_id(
+        raw.fetch('items', []) + raw.fetch('includes', {}).fetch('Entry', [])
+      )
+      @items.collect! { |item| build_entry(item['sys']['id']) }
+    end
+
+    private
+
+    def solve_link(value)
+      if value.is_a?(Array)
+        value.collect! { |link| solve_link(link) }.tap(&:compact!)
+      elsif value.is_a?(ContentfulLite::Link)
+        return nil if @errors.fetch(value.type, []).include?(value.id)
+
+        (value.type == :asset ? @assets[value.id] : build_entry(value.id)) || value
+      else
+        value
+      end
+    end
+
+    def hash_by_id(arr)
+      arr.each_with_object({}) do |element, hash|
+        hash[element['sys']['id']] = element
+      end
+    end
+
+    def build_entry(id)
+      @entries[id] || begin
+        hash = @raw_entries.delete(id)
+        return nil if hash.nil?
+
+        klass = ContentfulLite::Entry.get_class(hash['sys']['contentType']['sys']['id'])
+        @entries[id] = klass.new(hash)
+        @entries[id].localized_fields.values.each do |fields|
+          fields.transform_values! { |field| solve_link(field) }
+        end
+        @entries[id]
+      end
+    end
+  end
+end