wcc-contentful 1.3.0 → 1.4.0.rc1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: wcc-contentful
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0.rc1
 platform: ruby
 authors:
 - Watermark Dev
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-19 00:00:00.000000000 Z
+date: 2023-02-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -429,6 +429,7 @@ files:
 - lib/wcc/contentful/content_type_indexer.rb
 - lib/wcc/contentful/downloads_schema.rb
 - lib/wcc/contentful/engine.rb
+- lib/wcc/contentful/entry_locale_transformer.rb
 - lib/wcc/contentful/event.rb
 - lib/wcc/contentful/events.rb
 - lib/wcc/contentful/exceptions.rb
@@ -440,6 +441,7 @@ files:
 - lib/wcc/contentful/middleware.rb
 - lib/wcc/contentful/middleware/store.rb
 - lib/wcc/contentful/middleware/store/caching_middleware.rb
+- lib/wcc/contentful/middleware/store/locale_middleware.rb
 - lib/wcc/contentful/model.rb
 - lib/wcc/contentful/model_api.rb
 - lib/wcc/contentful/model_builder.rb
@@ -469,10 +471,12 @@ files:
 - 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/condition.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/locale_queries.rb
 - lib/wcc/contentful/store/rspec_examples/nested_queries.rb
 - lib/wcc/contentful/store/rspec_examples/operators.rb
 - lib/wcc/contentful/store/rspec_examples/operators/eq.rb
@@ -491,9 +495,9 @@ homepage: https://github.com/watermarkchurch/wcc-contentful/wcc-contentful
 licenses:
 - MIT
 metadata:
-  documentation_uri: https://watermarkchurch.github.io/wcc-contentful/1.3/wcc-contentful
+  documentation_uri: https://watermarkchurch.github.io/wcc-contentful/1.4/wcc-contentful
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -504,12 +508,12 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.3.7
+signing_key:
 specification_version: 4
 summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://rubygems.org/gems/wcc-contentful)
   [![Build Status](https://circleci.com/gh/watermarkchurch/wcc-contentful.svg?style=svg)](https://circleci.com/gh/watermarkchurch/wcc-contentful)
@@ -526,7 +530,7 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   Example](#advanced-configuration-example) 8. [Connecting to Multiple Spaces](#connecting-to-multiple-spaces-or-environments)
   9. [Development](#development) 10. [Contributing](#contributing) 11. [License](#license)   ##
   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
+  almost 5 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
@@ -620,19 +624,22 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   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
-  UTC...>  # Use operators to filter by a field # must use full notation for sys attributes
-  (except ID) WCC::Contentful::Model::Page.find_all(''sys.created_at'' => { lte: Date.today
-  }) # => [#<WCC::Contentful::Model::Page:0x0000000005c71a78 @created_at=2018-04-16
-  18:41:17 UTC...>, ... ]  # Nest queries to mimick joins WCC::Contentful::Model::Page.find_by(subpages:
-  { slug: ''/some-slug'' }) # => #<WCC::Contentful::Model::Page:0x0000000005c71a78
-  @created_at=2018-04-16 18:41:17 UTC...>  # Pass the preview flag to use the preview
-  client (must have set preview_token config param) preview_redirect = WCC::Contentful::Model::Redirect.find_by({
-  slug: ''draft-redirect'' }, preview: true) # => #<WCC::Contentful::Model::Redirect:0x0000000005d879ad
-  @created_at=2018-04-16 18:41:17 UTC...> preview_redirect_object.href # => ''http://www.somesite.com/slug-for-redirect''
+  entries of the `page` content type:  ```ruby # app/models/page.rb class Page < WCC::Contentful::Model::Page  #
+  You can add additional methods here end  # Find objects by id Page.find(''1E2ucWSdacxxf233sfa3'')
+  # => #<Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>  # Find objects
+  by field Page.find_by(slug: ''/some-slug'') # => #<Page:0x0000000005c71a78 @created_at=2018-04-16
+  18:41:17 UTC...>  # Use operators to filter by a field # must use full notation
+  for sys attributes (except ID) Page.find_all(''sys.created_at'' => { lte: Date.today
+  }) # => [#<Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>, ...
+  ]  # Nest queries to mimick joins Page.find_by(subpages: { slug: ''/some-slug''
+  }) # => #<Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>  # Fetch
+  an entry in a different locale spanish_homepage = Page.find_by(slug: ''/'', options:
+  { locale: ''es-US'' }) # => #<Page:0x0000000005c71a78 @created_at=2018-04-16 18:41:17
+  UTC...> spanish_homepage.title # => Esta es la página principal  # Pass the preview
+  flag to use the preview client (must have set preview_token config param) preview_redirect
+  = WCC::Contentful::Model::Redirect.find_by({ slug: ''draft-redirect'' }, preview:
+  true) # => #<WCC::Contentful::Model::Redirect:0x0000000005d879ad @created_at=2018-04-16
+  18:41:17 UTC...> preview_redirect_object.href # => ''http://www.somesite.com/slug-for-redirect''
   ```  See the {WCC::Contentful::Model} documentation for more details.  ### Store
   API  The Store layer is used by the Model API to access Contentful data in a raw
   form. The Store layer returns entries as hashes parsed from JSON, conforming to
@@ -643,12 +650,20 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   filter: { slug: ''/some-slug'' }) # => {"sys"=> #  ... # "fields"=> # ...}  query
   = store.find_all(content_type: ''page'').eq(''group'', ''some-group'') # => #<WCC::Contentful::Store::CDNAdapter::Query:0x00007fa3d40b84f0
   query.first # => {"sys"=> #  ... # "fields"=> # ...} query.result # => #<Enumerator::Lazy:
-  ...> query.result.force # => [{"sys"=> ...}, {"sys"=> ...}, ...] ```  See the {WCC::Contentful::Store}
-  documentation for more details.  ### Direct CDN API (SimpleClient)  The SimpleClient
-  is the bottom layer, and is used to get raw data directly from the Contentful CDN.  It
-  handles response parsing and paging, but does not resolve links or transform the
-  result into a Model class.  The following examples show how to use the SimpleClient
-  to retrieve data directly from the Contentful CDN:  ```ruby client = WCC::Contentful::Services.instance.client
+  ...> query.result.force # => [{"sys"=> ...}, {"sys"=> ...}, ...] ```  The store
+  layer, while superficially similar to the Contentful API, tries to present a different
+  "View" over the data which is more compatible with the Model layer.  It resolves
+  includes by actually replacing the in-memory `Link` objects with their linked `Entry`
+  representations.  This lets you traverse the links naturally using `#dig` or `#[]`:  ```ruby
+  # Include to a depth of 3 to make sure it''s included homepage = store.find_by(slug:
+  ''/'', include: 3) # Traverse through the top nav menu => menu button 0 => about
+  page about_page = homepage.dig(''fields'', ''nav_menu'', ''fields'', ''buttons'',
+  0, ''fields'', ''page'') ```   See the {WCC::Contentful::Store} documentation for
+  more details.  ### Direct CDN API (SimpleClient)  The SimpleClient is the bottom
+  layer, and is used to get raw data directly from the Contentful CDN.  It handles
+  response parsing and paging, but does not resolve links or transform the result
+  into a Model class.  The following examples show how to use the SimpleClient to
+  retrieve data directly from the Contentful CDN:  ```ruby client = WCC::Contentful::Services.instance.client
   # => #<WCC::Contentful::SimpleClient::Cdn:0x00007fa3cde89310  response = client.entry(''5FsqsbMECsM62e04U8sY4Y'')
   # => #<WCC::Contentful::SimpleClient::Response:0x00007fa3d103a4e0 response.body
   # => "{\n  \"sys\": {\n ... response.raw # => {"sys"=> #  ... # "fields"=> # ...}  client.asset(''5FsqsbMECsM62e04U8sY4Y'').raw
@@ -704,27 +719,44 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   example, the {WCC::Contentful::Store::MemoryStore} uses this to update the hash
   with the newest version of an entry, or delete an entry out of the hash.  #### Store
   Middleware  The store layer is made up of a base store (which implements {WCC::Contentful::Store::Interface}),
-  and optional middleware.  The middleware allows custom transformation of received
-  entries via the `#select` and `#transform` methods.  To create your own middleware
-  simply include {WCC::Contentful::Middleware::Store} and implement those methods,
-  then call `use` when configuring the store:  ```ruby config.store :direct do use
-  MyMiddleware, param1: ''xxx'' end ```  The most useful middleware is the {WCC::Contentful::Middleware::Store::CachingMiddleware},
-  which enables `:lazy_sync` mode (see {WCC::Contentful::Configuration#store})  ###
-  Model Layer  This is the global top layer where your Rails app looks up content
-  similarly to ActiveModel.  The models are namespaced under the root class {WCC::Contentful::Model}.
-  Each model''s implementation of `.find`, `.find_by`, and `.find_all` simply call
-  into the configured Store.  The main benefit of the Model layer is lazy link resolution.  When
-  a model''s property is accessed, if that property is a link that has not been resolved
-  yet (for example using the `include: n` parameter on `.find_by`), the model will
-  automatically call `#find` on the store to resolve that linked entry.  Note that
-  this can easily result in lots of CDN calls to Contentful!  To optimize this you
-  should use the `include` parameter and/or use a different store.  ## 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
+  and some required middleware.  The list of default middleware applied to each store
+  is found in {WCC::Contentful::Store::Factory.default_middleware}  To create your
+  own middleware simply include {WCC::Contentful::Middleware::Store}.  Then you can
+  optionally implement the `#transform` and `#select?` methods:  ```ruby class MyMiddleware
+  include WCC::Contentful::Middleware::Store  # Called for each entry that is requested
+  out of the backing store.  You can modify the entry and return it to the # next
+  layer. def transform(entry, options) # Do something with the entry... # Make sure
+  you return it at the end! entry end  def select?(entry, options) # Choose whether
+  this entry should exist or not.  If you return false here, then the entry will act
+  as though it # were archived in Contentful. entry.dig(''fields'', ''hide_until'')
+  > Time.zone.now end end ```  You can also override any of the standard Store methods.  To
+  apply the middleware, call `use` when configuring the store:  ```ruby config.store
+  :direct do use MyMiddleware, param1: ''xxx'' end ```  The most useful middleware
+  is the {WCC::Contentful::Middleware::Store::CachingMiddleware}, which enables `:lazy_sync`
+  mode (see {WCC::Contentful::Configuration#store})  ### Model Layer  This is the
+  global top layer where your Rails app looks up content similarly to ActiveModel.  The
+  models are namespaced under the root class {WCC::Contentful::Model}. Each model''s
+  implementation of `.find`, `.find_by`, and `.find_all` simply call into the configured
+  Store.  Models can be initialized directly with the `.new` method, by passing in
+  a hash: ```ruby entry = { ''sys'' => ..., ''fields'' => ... } Page.new(entry) ```  **The
+  initializer must receive a localized entry**.  An entry found using a `locale=*`
+  query must be transformed to a localized entry using the {WCC::Contentful::EntryLocaleTransformer}
+  before passing it to your model:  ```ruby entry = client.entry(''1234'', locale:
+  ''*'').raw localized_entry = WCC::Contentful::EntryLocaleTransformer.transform_to_locale(entry,
+  ''en-US'') Page.new(localized_entry) ```  The Store layer ensures that localized
+  entries are returned using the {WCC::Contentful::Middleware::Store::LocaleMiddleware}.  The
+  main benefit of the Model layer is lazy link resolution.  When a model''s property
+  is accessed, if that property is a link that has not been resolved yet (for example
+  using the `include: n` parameter on `.find_by`), the model will automatically call
+  `#find` on the store to resolve that linked entry.  Note that this can easily result
+  in lots of CDN calls to Contentful!  To optimize this you should use the `include`
+  parameter and/or use a different store.  ## 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>  ##
@@ -766,14 +798,19 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   step.  However the gem is also capable of connecting to multiple spaces within the
   same ruby process!  You just have to create and initialize a namespace.  The {WCC::Contentful::ModelAPI}
   concern makes this straightforward.  Start by creating your Namespace and including
-  the concern: ```ruby # app/models/my_second_space.rb class MySecondSpace include
-  WCC::Contentful::ModelAPI end  # app/models/other_page.rb class OtherPage < MySecondSpace::Page
-  end ```  Then configure it in an initializer: ```ruby # config/initializers/my_second_space.rb
+  the concern: ```ruby # lib/my_second_space.rb  # Note: This class must be in the
+  "lib" folder in :zeitwerk mode, otherwise Rails 6+ will unload all your constants
+  # that were created in the initializer.  Your models which subclass this namespace
+  may reside in the app/models directory. class MySecondSpace include WCC::Contentful::ModelAPI
+  end  # app/models/other_page.rb class OtherPage < MySecondSpace::Page end ```  Then
+  configure it in an initializer: ```ruby # config/initializers/my_second_space.rb
   MySecondSpace.configure do |config| # Make sure to point to a different schema file
   from your first space! config.schema_file = Rails.root.join(''db/second-contentful-schema.json'')  config.access_token
   = ENV[''SECOND_CONTENTFUL_ACCESS_TOKEN''] config.preview_token = ENV[''SECOND_CONTENTFUL_PREVIEW_ACCESS_TOKEN'']
   config.space = ENV[''SECOND_CONTENTFUL_SPACE_ID''] config.environment = ENV[''CONTENTFUL_ENVIRONMENT'']
-  end ```  Finally, use it: ```ruby OtherPage.find(''1234'') # GET https://cdn.contentful.com/spaces/other-space/environments/other-env/entries/1234
+  end  # Ensure that models are reloaded in Rails development mode Rails.application.config.to_prepare
+  do MySecondSpace.reload! end ```  Finally, use it: ```ruby OtherPage.find(''1234'')
+  # GET https://cdn.contentful.com/spaces/other-space/environments/other-env/entries/1234
   # => #<OtherPage:0x0000000005c71a78 @created_at=2018-04-16 18:41:17 UTC...>  Page.find(''1234'')
   # GET https://cdn.contentful.com/spaces/first-space/environments/first-env/entries/1234
   # => #<Page:0x0000000001271b70 @created_at=2018-04-15 12:02:14 UTC...> ```  The
@@ -783,14 +820,27 @@ summary: '[![Gem Version](https://badge.fury.io/rb/wcc-contentful.svg)](https://
   preview_client = MySecondSpace.services.preview_client # => #<WCC::Contentful::SimpleClient::Preview:0x00007f888ccafa00
   sync_engine = MySecondSpace.services.sync_engine # => #<WCC::Contentful::SyncEngine:0x00007f88960b6b40
   ``` Note that the above services are not accessible on {WCC::Contentful::Services.instance}
-  or via the {WCC::Contentful::ServiceAccessors}.  ### Using a sync store with a second
-  space  If you use something other than the CDNAdapter with your second space, you
-  will need to find a way to trigger `MySecondSpace.services.sync_engine.next` to
-  keep it up-to-date.  The {WCC::Contentful::Engine} will only manage the global SyncEngine
-  configured by the global {WCC::Contentful.configure}.  The easiest way to do this
-  is to set up your own Rails route to respond to Contentful webhooks and then configure
-  the second Contentful space to send webhooks to this route. You could also do this
-  by triggering it periodically in a background job using Sidekiq and [sidekiq-scheduler](https://github.com/Moove-it/sidekiq-scheduler).  ##
+  or via the {WCC::Contentful::ServiceAccessors}.  #### Important Note when using
+  Zeitwerk with Rails 6+ When using Rails >= 6 with `config.autoloader = :zeitwerk`,
+  Rails will remove any models defined in `app/models` after initialization and then
+  load them again when they are referenced.  If you `include WCC::Contentful::ModelAPI`
+  in a class defined inside the `app` directory, this will have the effect of deleting
+  all configuration that was set in the initializer as well as the constants generated
+  from your schema. This will result in one of two errors:  * `NameError (uninitialized
+  constant MySecondSpace::MyContentType)`   if you try to reference a subclass such
+  as `MyContentType < MySecondSpace::MyContentType` * `ArgumentError (Not yet configured!)`
+  if you try to `MySecondSpace.find(''xxxx'')` to load an Entry or Asset  The solution
+  is to have your secondary namespace in a folder which is not in the `autoload_paths`.
+  We suggest using `lib`, which will work so long as you have not added the `lib`
+  folder to the `autoload_paths` as some uninformed StackOverflow answers suggest
+  you do.  ### Using a sync store with a second space  If you use something other
+  than the CDNAdapter with your second space, you will need to find a way to trigger
+  `MySecondSpace.services.sync_engine.next` to keep it up-to-date.  The {WCC::Contentful::Engine}
+  will only manage the global SyncEngine configured by the global {WCC::Contentful.configure}.  The
+  easiest way to do this is to set up your own Rails route to respond to Contentful
+  webhooks and then configure the second Contentful space to send webhooks to this
+  route. You could also do this by triggering it periodically in a background job
+  using Sidekiq and [sidekiq-scheduler](https://github.com/Moove-it/sidekiq-scheduler).  ##
   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