wcc-contentful 0.4.0.pre.alpha → 1.0.0.pre.rc3

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: wcc-contentful
 version: !ruby/object:Gem::Version
-  version: 0.4.0.pre.alpha
+  version: 1.0.0.pre.rc3
 platform: ruby
 authors:
 - Watermark Dev
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2018-10-17 00:00:00.000000000 Z
+date: 2021-03-23 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 11.0.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 11.0.1
 - !ruby/object:Gem::Dependency
   name: coveralls
   requirement: !ruby/object:Gem::Requirement
@@ -38,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: erb_lint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.26
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.26
 - !ruby/object:Gem::Dependency
   name: httplog
   requirement: !ruby/object:Gem::Requirement
@@ -58,14 +86,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -80,34 +108,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-instrumentation-matcher
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec_junit_formatter
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.4.1
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0.52'
+        version: '0.68'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - '='
       - !ruby/object:Gem::Version
-        version: '0.52'
+        version: '0.68'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -128,14 +170,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
@@ -150,6 +192,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: wisper-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: guard
   requirement: !ruby/object:Gem::Requirement
@@ -193,61 +249,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 1.3.0
 - !ruby/object:Gem::Dependency
-  name: generator_spec
+  name: guard-shell
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.4
+        version: 0.7.1
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.4
+        version: 0.7.1
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: generator_spec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: 0.9.4
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.1'
+        version: 0.9.4
 - !ruby/object:Gem::Dependency
-  name: rspec-rails
+  name: sqlite3
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.7'
+        version: 1.3.6
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.7'
-- !ruby/object:Gem::Dependency
-  name: sqlite3
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.3.6
 - !ruby/object:Gem::Dependency
   name: timecop
   requirement: !ruby/object:Gem::Requirement
@@ -263,47 +305,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: 0.9.1
 - !ruby/object:Gem::Dependency
-  name: contentful
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 2.6.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - '='
-      - !ruby/object:Gem::Version
-        version: 2.6.0
-- !ruby/object:Gem::Dependency
-  name: contentful-management
+  name: connection_pool
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.2
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '='
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.0.2
+        version: '2.2'
 - !ruby/object:Gem::Dependency
-  name: graphql
+  name: faraday
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '0.9'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.7'
+        version: '0.9'
 - !ruby/object:Gem::Dependency
   name: http
   requirement: !ruby/object:Gem::Requirement
@@ -367,33 +395,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '5'
 - !ruby/object:Gem::Dependency
-  name: dry-validation
+  name: wcc-base
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.1
+        version: 0.3.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.11.1
+        version: 0.3.1
 - !ruby/object:Gem::Dependency
-  name: wcc-base
+  name: wisper
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.1
+        version: 2.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.1
+        version: 2.0.0
 description: Contentful API wrapper library exposing an ActiveRecord-like interface
 email:
 - dev@watermark.org
@@ -402,12 +430,11 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rspec"
-- Gemfile
 - Guardfile
 - README.md
+- Rakefile
 - app/controllers/wcc/contentful/application_controller.rb
 - app/controllers/wcc/contentful/webhook_controller.rb
-- app/jobs/wcc/contentful/delayed_sync_job.rb
 - app/jobs/wcc/contentful/webhook_enable_job.rb
 - bin/console
 - bin/rails
@@ -415,42 +442,68 @@ files:
 - bin/setup
 - config/initializers/mime_types.rb
 - config/routes.rb
+- doc
+- lib/tasks/download_schema.rake
 - lib/wcc/contentful.rb
-- lib/wcc/contentful/client_ext.rb
+- lib/wcc/contentful/active_record_shim.rb
 - lib/wcc/contentful/configuration.rb
 - lib/wcc/contentful/content_type_indexer.rb
+- lib/wcc/contentful/downloads_schema.rb
 - lib/wcc/contentful/engine.rb
+- lib/wcc/contentful/event.rb
+- lib/wcc/contentful/events.rb
 - lib/wcc/contentful/exceptions.rb
-- lib/wcc/contentful/graphql.rb
-- lib/wcc/contentful/graphql/builder.rb
-- lib/wcc/contentful/graphql/types.rb
 - lib/wcc/contentful/helpers.rb
 - lib/wcc/contentful/indexed_representation.rb
+- lib/wcc/contentful/instrumentation.rb
+- lib/wcc/contentful/link.rb
+- lib/wcc/contentful/link_visitor.rb
+- lib/wcc/contentful/middleware.rb
+- lib/wcc/contentful/middleware/store.rb
+- lib/wcc/contentful/middleware/store/caching_middleware.rb
 - lib/wcc/contentful/model.rb
 - lib/wcc/contentful/model_builder.rb
 - lib/wcc/contentful/model_methods.rb
 - lib/wcc/contentful/model_singleton_methods.rb
 - lib/wcc/contentful/rails.rb
+- lib/wcc/contentful/rake.rb
+- lib/wcc/contentful/rspec.rb
 - lib/wcc/contentful/services.rb
 - lib/wcc/contentful/simple_client.rb
-- lib/wcc/contentful/simple_client/http_adapter.rb
 - lib/wcc/contentful/simple_client/management.rb
 - lib/wcc/contentful/simple_client/response.rb
 - lib/wcc/contentful/simple_client/typhoeus_adapter.rb
 - lib/wcc/contentful/store.rb
+- lib/wcc/contentful/store/README.md
 - lib/wcc/contentful/store/base.rb
 - lib/wcc/contentful/store/cdn_adapter.rb
-- lib/wcc/contentful/store/lazy_cache_store.rb
+- lib/wcc/contentful/store/factory.rb
+- lib/wcc/contentful/store/instrumentation.rb
+- lib/wcc/contentful/store/interface.rb
 - lib/wcc/contentful/store/memory_store.rb
 - lib/wcc/contentful/store/postgres_store.rb
+- lib/wcc/contentful/store/postgres_store/schema_1.sql
+- lib/wcc/contentful/store/postgres_store/schema_2.sql
+- lib/wcc/contentful/store/query.rb
+- lib/wcc/contentful/store/query/interface.rb
+- lib/wcc/contentful/store/rspec_examples.rb
+- lib/wcc/contentful/store/rspec_examples/basic_store.rb
+- lib/wcc/contentful/store/rspec_examples/include_param.rb
+- lib/wcc/contentful/store/rspec_examples/nested_queries.rb
+- lib/wcc/contentful/sync_engine.rb
 - lib/wcc/contentful/sys.rb
+- lib/wcc/contentful/test.rb
+- lib/wcc/contentful/test/attributes.rb
+- lib/wcc/contentful/test/double.rb
+- lib/wcc/contentful/test/factory.rb
 - lib/wcc/contentful/version.rb
 - wcc-contentful.gemspec
 homepage: https://github.com/watermarkchurch/wcc-contentful/wcc-contentful
 licenses:
 - MIT
-metadata: {}
-post_install_message: 
+metadata:
+  documentation_uri: https://watermarkchurch.github.io/wcc-contentful/1.0/wcc-contentful
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -465,24 +518,114 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.11
-signing_key: 
+rubyforge_project:
+rubygems_version: 2.7.6.2
+signing_key:
 specification_version: 4
-summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://badge.fury.io/rb/wcc-contentful)
-  [![CircleCI](https://circleci.com/gh/watermarkchurch/wcc-contentful.svg?style=svg)](https://circleci.com/gh/watermarkchurch/wcc-contentful)
+summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://rubygems.org/gems/wcc-contentful)
+  [![Build Status](https://travis-ci.org/watermarkchurch/wcc-contentful.svg?branch=master)](https://travis-ci.org/watermarkchurch/wcc-contentful)
   [![Coverage Status](https://coveralls.io/repos/github/watermarkchurch/wcc-contentful/badge.svg?branch=master)](https://coveralls.io/github/watermarkchurch/wcc-contentful?branch=master)  Full
-  documentation: https://www.rubydoc.info/github/watermarkchurch/wcc-contentful  #
-  WCC::Contentful  ## Installation  Add this line to your application''s Gemfile:  ```ruby
-  gem ''wcc-contentful'', require: ''wcc/contentful/rails'' ```  And then execute:  $
-  bundle  Or install it yourself as:  $ gem install wcc-contentful  ## Configure  ```ruby
-  WCC::Contentful.configure do |config| config.access_token = <CONTENTFUL_ACCESS_TOKEN>
-  config.space = <CONTENTFUL_SPACE_ID> end  WCC::Contentful.init! ```  ## Usage  ###
-  WCC::Contentful::Model API  The WCC::Contentful::Model API exposes Contentful data
-  as a set of dynamically generated Ruby objects.  These objects are based on the
-  content types in your Contentful space.  All these objects are generated by WCC::Contentful.init!  The
-  following examples show how to use this API to find entries of the `page` content
-  type:  ```ruby # Find objects by id WCC::Contentful::Model::Page.find(''1E2ucWSdacxxf233sfa3'')
+  documentation: https://watermarkchurch.github.io/wcc-contentful/latest/wcc-contentful/  #
+  WCC::Contentful  An alternative to Contentful''s [contentful.rb ruby client](https://github.com/contentful/contentful.rb/),
+  [contentful_model](https://github.com/contentful/contentful_model), and [contentful_rails](https://github.com/contentful/contentful_rails)
+  gems all in one.  Table of Contents:  1. [Why?](#why-did-you-rewrite-the-contentful-ruby-stack)
+  2. [Installation](#installation)  ## Why did you rewrite the Contentful ruby stack?  We
+  started working with Contentful almost 3 years ago.  Since that time, Contentful''s
+  ruby stack has improved, but there are still a number of pain points that we feel
+  we have addressed better with our gem.  These are:  * [Low-level caching](#low-level-caching)
+  * [Better integration with Rails & Rails models](#better-rails-integration) * [Automatic
+  pagination and Automatic link resolution](#automatic-pagination-and-link-resolution)
+  * [Automatic webhook management](#automatic-webhook-management)  Our gem no longer
+  depends on any of the Contentful gems and interacts directly with the [Contentful
+  CDA](https://www.contentful.com/developers/docs/references/content-delivery-api/)
+  and [Content Management API](https://www.contentful.com/developers/docs/references/content-management-api/)
+  over HTTPS.  ### Low-level caching  The wcc-contentful gem enables caching at two
+  levels: the HTTP response using [Faraday HTTP cache middleware](https://github.com/sourcelevel/faraday-http-cache),
+  and at the Entry level using the Rails cache and the [Sync API](https://www.contentful.com/developers/docs/references/content-delivery-api/#/reference/synchronization)
+  to keep it up to date.  We''ve found these two cache layers to be very effective
+  at reducing both round trip latency to the Content Delivery API, as well as reducing
+  our monthly API request usage. (which reduces our overage charges.  Hooray!)  ####
+  At the request/response level By default, the contentful.rb gem requires the [HTTP
+  library](https://rubygems.org/gems/http).  While simple and straightforward to use,
+  it is not as powerful for caching.  We decided to make our client conform to the
+  [Faraday gem''s API](https://github.com/lostisland/faraday).  If you prefer not
+  to use Faraday, you can choose to supply your own HTTP adapter that "quacks like"
+  Faraday (see the [TyphoeusAdapter](https://github.com/watermarkchurch/wcc-contentful/blob/master/wcc-contentful/lib/wcc/contentful/simple_client/typhoeus_adapter.rb)
+  for one implementation).  Using Faraday makes it easy to add Middleware.  As an
+  example, our flagship Rails app that powers watermark.org uses the following configuration
+  in Production, which provides us with instrumentation through statsd, logging, and
+  caching: ```rb config.connection = Faraday.new do |builder| builder.use :http_cache,
+  shared_cache: false, store: ActiveSupport::Cache::MemoryStore.new(size: 512.megabytes),
+  logger: Rails.logger, serializer: Marshal, instrumenter: ActiveSupport::Notifications  builder.use
+  :gzip builder.response :logger, Rails.logger, headers: false, bodies: false if Rails.env.development?
+  builder.request :instrumentation builder.adapter :typhoeus end ```  #### At the
+  Entry level  Our stack has three layers, the middle layer being essentially a cache
+  for individual Entry hashes parsed out of responses from the Delivery API.  We were
+  able to add a caching layer here which stores entries retrieved over the Sync API,
+  and responds to queries with cached versions of local content when possible.  We
+  consider this to be our best innovation on the Contentful ruby stack.  We have successfully
+  created caching layers using Memcached, Postgres, and an in-memory hash.  The architecture
+  allows other caching implementations to be created fairly easily, and we have a
+  set of rspec specs that can verify that a cache store behaves appropriately.  For
+  more information, [see the documentation on the caching modes here](https://watermarkchurch.github.io/wcc-contentful/latest/wcc-contentful/WCC/Contentful/Store.html).  ###
+  Better Rails Integration  When we initially got started with the Contentful ruby
+  models, we encountered one problem that was more frustrating than all others: If
+  a field exists in the content model, but the particular entry we''re working with
+  does not have that field populated, then accessing that field raised a `NoMethodError`.  This
+  caused us to litter our code with `if defined?(entry.my_field)` which is bad practice.  (Note:
+  this has since been fixed in contentful.rb v2).  We decided it was better to not
+  rely on `method_missing?` (what contentful.rb does), and instead to use `define_method`
+  in an initializer to generate the methods for our models.  This has the advantage
+  that calling `.instance_methods` on a model class includes all the fields present
+  in the content model.  We also took advantage of Rails'' naming conventions to automatically
+  infer the content type name based on the class name.  Thus in our code, we have
+  `app/models/page.rb` which defines `class Page << WCC::Contentful::Model::Page`,
+  and is automatically linked to the `page` content type ID.  (Note: this is overridable
+  on a per-model basis)  All our models are automatically generated at startup which
+  improves response times at the expense of initialization time.  In addition, our
+  content model registry allows easy definition of custom models in your `app/models`
+  directory to override fields.  This plays nice with other gems like algoliasearch-rails,
+  which allows you to declaratively manage your Algolia indexes.  Another example
+  from our flagship watermark.org:  ```rb class Page < WCC::Contentful::Model::Page
+  include AlgoliaSearch  algoliasearch(index_name: ''pages'') do attribute(:title,
+  :slug) ... end ```  ### Automatic Pagination and Link Resolution  Using the `contentful_model`
+  gem, calling `Page.all.load` does not give you all Page entries if there are more
+  than 100.  To get the next page you must call `.paginate` on the response.  By contrast,
+  `Page.find_all` in the `wcc-contentful` gem gives you a [Lazy Enumerator](https://ruby-doc.org/core-2.5.0/Enumerator/Lazy.html).  As
+  you iterate past the 100th entry, the enumerator will automatically fetch the next
+  page.  If you only enumerate 99 entries (say with `.take(99)`), then the second
+  page will never be fetched.  Similarly, if your Page references an asset, say `hero_image`,
+  that field returns a `Link` object rather than the actual `Asset`.  You must either
+  predefine how many links you need using `Page.load_children(3).all.load`, or detect
+  that `hero_image` is a `Link` like `if @page.hero_image.is_a? Contentful::Link`
+  and then call `.resolve` on the link.  We found all of that to be too cumbersome
+  when we are down in a nested partial view template that may be invoked from multiple
+  places.  The `wcc-contentful` gem, by contrast, automatically resolves a link when
+  accessing the associated attribute.  So in our example above, `wcc-contentful` will
+  **always** return a `WCC::Contentful::Asset` when calling `@page.hero_image`, even
+  if it has to execute a query to cdn.contentful.com in order to fetch it.  Warning:
+  This can easily lead to you exhausting your Contentful API quota if you do not carefully
+  tune your cache, which you should be doing anyways!  The default settings will use
+  the Rails cache to try to cache these resolutions, but *you are ultimately responsible
+  for how many queries you execute!*  ### Automatic webhook management  The `wcc-contentful`
+  gem, just like `contentful_rails`, provides an Engine to be mounted in your Rails
+  routes file.  Unlike `contentful_rails`, if you also configure `wcc-contentful`
+  with a Contentful Management Token and a public `app_url`, then on startup the `wcc-contentful`
+  engine will reach out to the Contentful Management API and ensure that a webhook
+  is configured to point to your app.  This is one less devops burden on you, and
+  plays very nicely in with Heroku review apps.  ## Installation  Add this line to
+  your application''s Gemfile:  ```ruby gem ''wcc-contentful'', require: ''wcc/contentful/rails''
+  ```  If you''re not using rails, exclude the `require:` parameter.  ```ruby gem
+  ''wcc-contentful'' ```  And then execute:  ``` $ bundle ```  Or install it yourself:  ```
+  $ gem install wcc-contentful ```  ## Configure  Put this in an initializer:  ```ruby
+  # config/initializers/wcc_contentful.rb WCC::Contentful.configure do |config| config.access_token
+  = <CONTENTFUL_ACCESS_TOKEN> config.space = <CONTENTFUL_SPACE_ID> end  WCC::Contentful.init!
+  ```  All configuration options can be found [in the rubydoc under WCC::Contentful::Configuration](https://watermarkchurch.github.io/wcc-contentful/latest/wcc-contentful/WCC/Contentful/Configuration)   ##
+  Usage  ### WCC::Contentful::Model API  The WCC::Contentful::Model API exposes Contentful
+  data as a set of dynamically generated Ruby objects.  These objects are based on
+  the content types in your Contentful space.  All these objects are generated by
+  `WCC::Contentful.init!`  The following examples show how to use this API to find
+  entries of the `page` content type:  ```ruby # Find objects by id WCC::Contentful::Model::Page.find(''1E2ucWSdacxxf233sfa3'')
   # => #<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17
   UTC...>  # Find objects by field WCC::Contentful::Model::Page.find_by(slug: ''/some-slug'')
   # => #<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17
@@ -522,32 +665,72 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   #   {"sys"=> ...} #  "6Fwukxxkxa6qQCC04WCaqg"=> #   {"sys"=> ...} #   ...} ```  The
   client handles Paging automatically within the lazy iterator returned by #items.
   This lazy iterator does not respect the `limit` param - that param is only passed
-  through to the API to set the page size.  Entries included via the `include` parameter
-  are made available on the #includes field.  This is a hash of `<entry ID> => <raw
-  entry>` and makes it easy to grab links.  This hash is added to lazily as you enumerate
-  the pages.  See the {WCC::Contentful::SimpleClient} documentation for more details.  ###
-  Accessing the APIs within application code  The Model API is best exposed by defining
-  your own model classes in the `app/models` directory which inherit from the WCC::Contentful
-  models.  ```ruby # app/models/page.rb class Page < WCC::Contentful::Model::Page  #
-  You can add additional methods here end  # app/controllers/pages_controller.rb class
-  PagesController < ApplicationController def show @page = Page.find_by(slug: params[:slug])
-  raise Exceptions::PageNotFoundError, params[:slug] unless @page end end ```  The
-  {WCC::Contentful::Services} singleton gives access to the other configured services.
-  You can also include the {WCC::Contentful::ServiceAccessors} concern to define these
-  services as attributes in a class.  ```ruby class MyJob < ApplicationJob include
-  WCC::Contentful::ServiceAccessors  def perform Page.find(...)  store.find(...)  client.entries(...)
-  end end ```  ## Development  After checking out the repo, run `bin/setup` to install
-  dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console`
-  for an interactive prompt that will allow you to experiment.  To install this gem
-  onto your local machine, run `bundle exec rake install`. To release a new version,
-  update the version number in `version.rb`, and then run `bundle exec rake release`,
-  which will create a git tag for the version, push git commits and tags, and push
-  the `.gem` file to [rubygems.org](https://rubygems.org).  ## Contributing  Bug reports
-  and pull requests are welcome on GitHub at https://github.com/watermarkchurch/wcc-contentful.
-  This project is intended to be a safe, welcoming space for collaboration, and contributors
-  are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org)
-  code of conduct.  ## License  The gem is available as open source under the terms
-  of the [MIT License](http://opensource.org/licenses/MIT).  ## Code of Conduct  Everyone
+  through to the API to set the page size.  If you truly want a limited subset of
+  response items, use [`response.items.take(n)`](https://ruby-doc.org/core-2.5.3/Enumerable.html#method-i-take)  Entries
+  included via the `include` parameter are made available on the #includes field.  This
+  is a hash of `<entry ID> => <raw entry>` and makes it easy to grab links.  This
+  hash is added to lazily as you enumerate the pages.  See the {WCC::Contentful::SimpleClient}
+  documentation for more details.  ### Accessing the APIs within application code  The
+  Model API is best exposed by defining your own model classes in the `app/models`
+  directory which inherit from the WCC::Contentful models.  ```ruby # app/models/page.rb
+  class Page < WCC::Contentful::Model::Page  # You can add additional methods here
+  end  # app/controllers/pages_controller.rb class PagesController < ApplicationController
+  def show @page = Page.find_by(slug: params[:slug]) raise Exceptions::PageNotFoundError,
+  params[:slug] unless @page end end ```  The {WCC::Contentful::Services} singleton
+  gives access to the other configured services. You can also include the {WCC::Contentful::ServiceAccessors}
+  concern to define these services as attributes in a class.  ```ruby class MyJob
+  < ApplicationJob include WCC::Contentful::ServiceAccessors  def perform Page.find(...)  store.find(...)  client.entries(...)
+  end end ```  ## Architecture  ![wcc-contentful diagram](./doc/wcc-contentful.png)  ##
+  Test Helpers  To use the test helpers, include the following in your rails_helper.rb:  ```ruby
+  require ''wcc/contentful/rspec'' ```  This adds the following helpers to all your
+  specs:  ```ruby ## # Builds a in-memory instance of the Contentful model for the
+  given content_type. # All attributes that are known to be required fields on the
+  content type # will return a default value based on the field type. instance = contentful_create(''my-content-type'',
+  my_field: ''some-value'') # => #<WCC::Contentful::Model::MyContentType:0x0000000005c71a78
+  @created_at=2018-04-16 18:41:17 UTC...>  instance.my_field # => "some-value"  instance.other_required_field
+  # => "default-value"  instance.other_optional_field # => nil  instance.not_a_field
+  # NoMethodError: undefined method `not_a_field'' for #<MyContentType:0x00007fbac81ee490>  ##
+  # Builds a rspec double of the Contentful model for the given content_type. # All
+  attributes that are known to be required fields on the content type # will return
+  a default value based on the field type. dbl = contentful_double(''my-content-type'',
+  my_field: ''other-value'') # => #<Double (anonymous)>  dbl.my_field # => "other-value"  dbl.other_optional_field
+  # => nil  dbl.not_a_field # => #<Double (anonymous)> received unexpected message
+  :not_a_field with (no args)  ## # Builds out a fake Contentful entry for the given
+  content type, and then # stubs the Model API to return that content type for `.find`
+  and `.find_by` # query methods. stubbed = contentful_stub(''my-content-type'', id:
+  ''1234'', my_field: ''test'')  WCC::Contentful::Model.find(''1234'') == stubbed
+  # => true  MyContentType.find(''1234'') == stubbed # => true  MyContentType.find_by(my_field:
+  ''test'') == stubbed # => true ```  ## Advanced Configuration Example  Here''s an
+  example containing all the configuration options, and a sample setup for automatic
+  deployment to Heroku.  This is intended to make you aware of what is possible, and
+  not as a general recommendation of what your setup should look like.  ```ruby #
+  config/initializers/wcc_contentful.rb WCC::Contentful.configure do |config| config.access_token
+  = ENV[''CONTENTFUL_ACCESS_TOKEN''] config.space = ENV[''CONTENTFUL_SPACE_ID''] config.environment
+  = ENV[''CONTENTFUL_ENVIRONMENT''] config.preview_token = ENV[''CONTENTFUL_PREVIEW_ACCESS_TOKEN'']  #
+  You may or may not want to provide this to your production server... config.management_token
+  = ENV[''CONTENTFUL_MANAGEMENT_TOKEN''] unless Rails.env.production?  config.app_url
+  = "https://#{ENV[''HOSTNAME'']}" config.webhook_username = ''my-app-webhook'' config.webhook_password
+  = Rails.application.secrets.webhook_password config.webhook_jobs << MyOnWebhookJob  config.store
+  = :lazy_sync, Rails.cache if Rails.env.production? # config.store = MyCustomStore.new  #
+  Use a custom Faraday connection config.connection = Faraday.new do |builder| f.request
+  :retry f.request MyFaradayRequestAdapter.new ... end # OR implement some adapter
+  like this to use another HTTP client config.connection = MyNetHttpAdapter.new  config.update_schema_file
+  = :never end  WCC::Contentful.init! ```  For Heroku:  ```yaml # Procfile web: bundle
+  exec rails s worker: bundle exec sidekiq release: bin/release ```  ```sh # bin/release
+  #!/bin/sh  set -e  echo "Migrating database..." bin/rake db:migrate  echo "Migrating
+  contentful..." migrations_to_be_run=$( ... ) # somehow figure this out node_modules/.bin/contentful-migration
+  \ -s $CONTENTFUL_SPACE_ID -a $CONTENTFUL_MANAGEMENT_TOKEN \ -y -p "$migrations_to_be_run"  echo
+  "Updating schema file..." rake wcc_contentful:download_schema ```  All configuration
+  options can be found [in the rubydoc](https://www.rubydoc.info/gems/wcc-contentful/WCC/Contentful/Configuration)
+  under {WCC::Contentful::Configuration}   ## Development  After checking out the
+  repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to
+  run the tests. You can also run `bin/console` for an interactive prompt that will
+  allow you to experiment.  ## Contributing  Bug reports and pull requests are welcome
+  on GitHub at https://github.com/watermarkchurch/wcc-contentful. This project is
+  intended to be a safe, welcoming space for collaboration, and contributors are expected
+  to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of
+  conduct.  ## License  The gem is available as open source under the terms of the
+  [MIT License](http://opensource.org/licenses/MIT).  ## Code of Conduct  Everyone
   interacting in the WCC::Contentful project''s codebases, issue trackers, chat rooms
   and mailing lists is expected to follow the [code of conduct](https://github.com/watermarkchurch/wcc-contentful/blob/master/CODE_OF_CONDUCT.md).'
 test_files: []