wcc-contentful 0.2.2 → 0.3.0.pre.rc

data/lib/wcc/contentful/model_singleton_methods.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# This module is extended by all models and defines singleton
+# methods that are not dynamically generated.
+# @api Model
+module WCC::Contentful::ModelSingletonMethods
+  def store(preview = false)
+    if preview
+      if WCC::Contentful::Model.preview_store.nil?
+        raise ArgumentError,
+          'You must include a contentful preview token in your WCC::Contentful.configure block'
+      end
+      WCC::Contentful::Model.preview_store
+    else
+      WCC::Contentful::Model.store
+    end
+  end
+
+  # Finds an instance of this content type.
+  #
+  # @return [nil, WCC::Contentful::Model] An instance of the appropriate model class
+  #   for this content type, or nil if the ID does not exist in the space.
+  # @example
+  #   WCC::Contentful::Model::Page.find(id)
+  def find(id, options: nil)
+    options ||= {}
+    raw = store(options[:preview])
+      .find(id, { hint: type }.merge!(options.except(:preview)))
+    new(raw, options) if raw.present?
+  end
+
+  # Finds all instances of this content type, optionally limiting to those matching
+  # a given filter query.
+  #
+  # @return [Enumerator::Lazy<WCC::Contentful::Model>, <WCC::Contentful::Model>]
+  #   A set of instantiated model objects matching the given query.
+  # @example
+  #   WCC::Contentful::Model::Page.find_all('sys.created_at' => { lte: Date.today })
+  def find_all(filter = nil)
+    filter = filter&.dup
+    options = filter&.delete(:options) || {}
+
+    if filter.present?
+      filter.transform_keys! { |k| k.to_s.camelize(:lower) }
+      bad_fields = filter.keys.reject { |k| self::FIELDS.include?(k) }
+      raise ArgumentError, "These fields do not exist: #{bad_fields}" unless bad_fields.empty?
+    end
+
+    query = store(options[:preview])
+      .find_all(content_type: content_type, options: options.except(:preview))
+    query = query.apply(filter) if filter.present?
+    query.map { |r| new(r, options) }
+  end
+
+  # Finds the first instance of this content type matching the given query.
+  #
+  # @return [nil, WCC::Contentful::Model] A set of instantiated model objects matching
+  #   the given query.
+  # @example
+  #   WCC::Contentful::Model::Page.find_by(slug: '/some-slug')
+  def find_by(filter = nil)
+    filter = filter&.dup
+    options = filter&.delete(:options) || {}
+
+    if filter.present?
+      filter.transform_keys! { |k| k.to_s.camelize(:lower) }
+      bad_fields = filter.keys.reject { |k| self::FIELDS.include?(k) }
+      raise ArgumentError, "These fields do not exist: #{bad_fields}" unless bad_fields.empty?
+    end
+
+    result = store(options[:preview])
+      .find_by(content_type: content_type, filter: filter, options: options.except(:preview))
+
+    new(result, options) if result
+  end
+
+  def inherited(subclass)
+    # only register if it's not already registered
+    return if WCC::Contentful::Model.registered?(content_type)
+
+    WCC::Contentful::Model.register_for_content_type(content_type, klass: subclass)
+  end
+end

data/lib/wcc/contentful/services.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module WCC::Contentful
+  class Services
+    include Singleton
+
+    # Gets the data-store which executes the queries run against the dynamic
+    # models in the WCC::Contentful::Model namespace.
+    # This is one of the following based on the configured content_delivery method:
+    #
+    # [:direct] an instance of {WCC::Contentful::Store::CDNAdapter} with a
+    #           {WCC::Contentful::SimpleClient::Cdn CDN Client} to access the CDN.
+    #
+    # [:lazy_sync] an instance of {WCC::Contentful::Store::LazyCacheStore}
+    #              with the configured ActiveSupport::Cache implementation and a
+    #              {WCC::Contentful::SimpleClient::Cdn CDN Client} for when data
+    #              cannot be found in the cache.
+    #
+    # [:eager_sync] an instance of the configured Store type, defined by
+    #               {WCC::Contentful::Configuration#sync_store}
+    #
+    # @api Store
+    def store
+      @store ||=
+        ensure_configured do |config|
+          WCC::Contentful::Store::Factory.new(
+            config,
+            self,
+            config.content_delivery,
+            config.content_delivery_params
+          ).build_sync_store
+        end
+    end
+
+    # An instance of {WCC::Contentful::Store::CDNAdapter} which connects to the
+    # Contentful Preview API to return preview content.
+    #
+    # @api Store
+    def preview_store
+      @preview_store ||=
+        ensure_configured do |config|
+          WCC::Contentful::Store::Factory.new(
+            config,
+            self,
+            :direct,
+            [{ preview: true }]
+          ).build_sync_store
+        end
+    end
+
+    # Gets a {WCC::Contentful::SimpleClient::Cdn CDN Client} which provides
+    # methods for getting and paging raw JSON data from the Contentful CDN.
+    #
+    # @api Client
+    def client
+      @client ||=
+        ensure_configured do |config|
+          WCC::Contentful::SimpleClient::Cdn.new(
+            access_token: config.access_token,
+            space: config.space,
+            default_locale: config.default_locale,
+            adapter: config.http_adapter,
+            environment: config.environment
+          )
+        end
+    end
+
+    # Gets a {WCC::Contentful::SimpleClient::Cdn CDN Client} which provides
+    # methods for getting and paging raw JSON data from the Contentful Preview API.
+    #
+    # @api Client
+    def preview_client
+      @preview_client ||=
+        ensure_configured do |config|
+          if config.preview_token.present?
+            WCC::Contentful::SimpleClient::Preview.new(
+              preview_token: config.preview_token,
+              space: config.space,
+              default_locale: config.default_locale,
+              adapter: config.http_adapter,
+              environment: config.environment
+            )
+          end
+        end
+    end
+
+    # Gets a {WCC::Contentful::SimpleClient::Management Management Client} which provides
+    # methods for updating data via the Contentful Management API
+    #
+    # @api Client
+    def management_client
+      @management_client ||=
+        ensure_configured do |config|
+          if config.management_token.present?
+            WCC::Contentful::SimpleClient::Management.new(
+              management_token: config.management_token,
+              space: config.space,
+              default_locale: config.default_locale,
+              adapter: config.http_adapter,
+              environment: config.environment
+            )
+          end
+        end
+    end
+
+    private
+
+    def ensure_configured
+      if WCC::Contentful.configuration.nil?
+        raise StandardError, 'WCC::Contentful has not yet been configured!'
+      end
+
+      yield WCC::Contentful.configuration
+    end
+  end
+
+  # Include this module to define accessors for every method defined on the
+  # {Services} singleton.
+  #
+  # @example
+  #   class MyJob < ApplicationJob
+  #     include WCC::Contentful::ServiceAccessors
+  #
+  #     def perform
+  #       Page.find(...)
+  #
+  #       store.find(...)
+  #
+  #       client.entries(...)
+  #     end
+  #   end
+  # @see Services
+  module ServiceAccessors
+    SERVICES = (WCC::Contentful::Services.instance_methods -
+      Object.instance_methods -
+      Singleton.instance_methods)
+
+    SERVICES.each do |m|
+      define_method m do
+        Services.instance.public_send(m)
+      end
+    end
+  end
+end

data/lib/wcc/contentful/simple_client.rb

@@ -1,33 +1,59 @@
 # frozen_string_literal: true
 
 require_relative 'simple_client/response'
+require_relative 'simple_client/management'
 
 module WCC::Contentful
-  ##
   # The SimpleClient accesses the Contentful CDN to get JSON responses,
-  # returning the raw JSON data as a parsed hash.
+  # returning the raw JSON data as a parsed hash.  This is the bottom layer of
+  # the WCC::Contentful gem.
+  #
+  # Note: Do not create this directly, instead create one of
+  # WCC::Contentful::SimpleClient::Cdn, WCC::Contentful::SimpleClient::Preview,
+  # WCC::Contentful::SimpleClient::Management
+  #
   # It can be configured to access any API url and exposes only a single method,
   # `get`.  This method returns a WCC::Contentful::SimpleClient::Response
   # that handles paging automatically.
   #
   # The SimpleClient by default uses 'http' to perform the gets, but any HTTP
   # client can be injected by passing a proc as the `adapter:` option.
+  #
+  # @api Client
   class SimpleClient
+    attr_reader :api_url
+    attr_reader :space
+
+    # Creates a new SimpleClient with the given configuration.
+    #
+    # @param [String] api_url the base URL of the Contentful API to connect to
+    # @param [String] space The Space ID to access
+    # @param [String] access_token A Contentful Access Token to be sent in the Authorization header
+    # @param [Hash] options The remaining optional parameters, defined below
+    # @option options [Symbol, Object] adapter The Adapter to use to make requests.
+    #   Auto-discovered based on what gems are installed if this is not provided.
+    # @option options [String] default_locale The locale query param to set by default.
+    # @option options [String] environment The contentful environment to access. Defaults to 'master'.
+    # @option options [Boolean] no_follow_redirects If true, do not follow 300 level redirects.
     def initialize(api_url:, space:, access_token:, **options)
       @api_url = URI.join(api_url, '/spaces/', space + '/')
       @space = space
       @access_token = access_token
 
-      @get_http = SimpleClient.load_adapter(options[:adapter])
+      @adapter = SimpleClient.load_adapter(options[:adapter])
 
       @options = options
       @query_defaults = {}
       @query_defaults[:locale] = @options[:default_locale] if @options[:default_locale]
 
-      return unless env = options[:environment]
-      @api_url = URI.join(@api_url, 'environments/', env + '/')
+      return unless options[:environment].present?
+
+      @api_url = URI.join(@api_url, 'environments/', options[:environment] + '/')
     end
 
+    # performs an HTTP GET request to the specified path within the configured
+    # space and environment.  Query parameters are merged with the defaults and
+    # appended to the request.
     def get(path, query = {})
       url = URI.join(@api_url, path)
 
@@ -79,7 +105,7 @@ module WCC::Contentful
       q = @query_defaults.dup
       q = q.merge(query) if query
 
-      resp = @get_http.call(url, q, headers, proxy)
+      resp = @adapter.call(url, q, headers, proxy)
 
       if [301, 302, 307].include?(resp.code) && !@options[:no_follow_redirects]
         resp = get_http(resp.headers['location'], nil, headers, proxy)
@@ -87,11 +113,12 @@ module WCC::Contentful
       resp
     end
 
-    ##
     # The CDN SimpleClient accesses 'https://cdn.contentful.com' to get raw
     # JSON responses.  It exposes methods to query entries, assets, and content_types.
     # The responses are instances of WCC::Contentful::SimpleClient::Response
     # which handles paging automatically.
+    #
+    # @api Client
     class Cdn < SimpleClient
       def initialize(space:, access_token:, **options)
         super(
@@ -106,42 +133,36 @@ module WCC::Contentful
         'cdn'
       end
 
-      ##
       # Gets an entry by ID
       def entry(key, query = {})
         resp = get("entries/#{key}", query)
         resp.assert_ok!
       end
 
-      ##
       # Queries entries with optional query parameters
       def entries(query = {})
         resp = get('entries', query)
         resp.assert_ok!
       end
 
-      ##
       # Gets an asset by ID
       def asset(key, query = {})
         resp = get("assets/#{key}", query)
         resp.assert_ok!
       end
 
-      ##
       # Queries assets with optional query parameters
       def assets(query = {})
         resp = get('assets', query)
         resp.assert_ok!
       end
 
-      ##
       # Queries content types with optional query parameters
       def content_types(query = {})
         resp = get('content_types', query)
         resp.assert_ok!
       end
 
-      ##
       # Accesses the Sync API to get a list of items that have changed since
       # the last sync.
       #
@@ -161,26 +182,7 @@ module WCC::Contentful
       end
     end
 
-    class Management < SimpleClient
-      def initialize(space:, management_token:, **options)
-        super(
-          api_url: options[:api_url] || 'https://api.contentful.com',
-          space: space,
-          access_token: management_token,
-          **options
-        )
-      end
-
-      def client_type
-        'management'
-      end
-
-      def content_types(**query)
-        resp = get('content_types', query)
-        resp.assert_ok!
-      end
-    end
-
+    # @api Client
     class Preview < Cdn
       def initialize(space:, preview_token:, **options)
         super(

data/lib/wcc/contentful/simple_client/http_adapter.rb

@@ -12,4 +12,13 @@ class HttpAdapter
       HTTP[headers].get(url, params: query)
     end
   end
+
+  def post(url, body, headers = {}, proxy = {})
+    if proxy[:host]
+      HTTP[headers].via(proxy[:host], proxy[:port], proxy[:username], proxy[:password])
+        .post(url, json: body)
+    else
+      HTTP[headers].post(url, json: body)
+    end
+  end
 end

data/lib/wcc/contentful/simple_client/management.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# @api Client
+class WCC::Contentful::SimpleClient::Management < WCC::Contentful::SimpleClient
+  def initialize(space:, management_token:, **options)
+    super(
+      api_url: options[:api_url] || 'https://api.contentful.com',
+      space: space,
+      access_token: management_token,
+      **options
+    )
+
+    @post_adapter = @adapter if @adapter.respond_to?(:post)
+    @post_adapter ||= self.class.load_adapter(nil)
+  end
+
+  def client_type
+    'management'
+  end
+
+  def content_types(**query)
+    resp = get('content_types', query)
+    resp.assert_ok!
+  end
+
+  def webhook_definitions(**query)
+    resp = get("/spaces/#{space}/webhook_definitions", query)
+    resp.assert_ok!
+  end
+
+  # {
+  #   "name": "My webhook",
+  #   "url": "https://www.example.com/test",
+  #   "topics": [
+  #     "Entry.create",
+  #     "ContentType.create",
+  #     "*.publish",
+  #     "Asset.*"
+  #   ],
+  #   "httpBasicUsername": "yolo",
+  #   "httpBasicPassword": "yolo",
+  #   "headers": [
+  #     {
+  #       "key": "header1",
+  #       "value": "value1"
+  #     },
+  #     {
+  #       "key": "header2",
+  #       "value": "value2"
+  #     }
+  #   ]
+  # }
+  def post_webhook_definition(webhook)
+    resp = post("/spaces/#{space}/webhook_definitions", webhook)
+    resp.assert_ok!
+  end
+
+  def post(path, body)
+    url = URI.join(@api_url, path)
+
+    Response.new(self,
+      { url: url, body: body },
+      post_http(url, body))
+  end
+
+  private
+
+  def post_http(url, body, headers = {}, proxy = {})
+    headers = {
+      Authorization: "Bearer #{@access_token}",
+      'Content-Type' => 'application/vnd.contentful.management.v1+json'
+    }.merge(headers || {})
+
+    resp = @post_adapter.post(url, body, headers, proxy)
+
+    if [301, 302, 307].include?(resp.code) && !@options[:no_follow_redirects]
+      resp = get_http(resp.headers['location'], nil, headers, proxy)
+    end
+    resp
+  end
+end