barkibu-kb 0.16.1

data/README.md

@@ -0,0 +1,243 @@
+# Barkibu's Knowledge Base API sdk
+
+A wrapper of Barkibu's Knowledge Base Endpoint to make those entities and their respective CRUD operations available to a ruby app.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'barkibu-kb'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install kb
+
+## Usage
+
+This gem wraps the Knowledge Base Api and exposes CRUD-_able_ entities into the requiring application.
+
+### Configuration
+
+The configuration of the connection to the Knowledge Base is done using ENV variable:
+
+- **KB_API_KEY**: the Knowledge Base API Key
+- **KB_PARTNER_KEY**: the Partner KB Key
+- **KB_API_URL_TEMPLATE**: the template url of the Knowledge Base where will be extrapolated _bounded_context_, _version_ and _entity_.
+
+  For instance: `https://dev.api.%{bounded_context}.barkkb.com/%{version}/%{entity}`.
+
+#### Cache configuration
+
+We add the ability to cache GET responses. To enable it, just set KB.config.cache properties:
+```ruby
+# config/initializers/kb_ruby.rb
+KB.config.cache.instance = Rails.cache # ActiveSupport::Cache::NullStore.new
+KB.config.cache.expires_in = 1.second # 0 by default
+KB.config.log_level = :debugger # :info by default
+```
+
+### Exposed Entities
+
+#### Pet Parent 🧍🏾
+
+`KB::PetParent` acts almost like an `ActiveRecord` implementing `ActiveModel::Model` exposing:
+
+- `find`
+  - arg: `key` string
+  - returns: a PetParent instance when provided an existing key or raise `ActiveRecord::RecordNotFound`
+- `create`
+  - arg: `attributes` to initialize the entity
+  - returns: the raw attributes of the created PetParent instance
+  - throws an `KB::Error` exception if something went wrong
+- `find_or_create_by`
+  - arg: `attributes`, `additional_attributes` to look for or initialize the entity
+  - returns: look for a PetParent matching the passed attributes or initialize and persist one with the given attributes and launching the block provided
+  - throws an `KB::Error` exception if something went wrong
+- `all`
+  - arg: `filters` hash of filters
+  - returns: an array of PetParent instances matching the filters
+- `save!`
+  - persists (create or update) the entity to the Knowledge Base
+  - throws an `KB::Error` exception if something went wrong
+- `destroy!`
+  - deletes the entity in the Knowledge Base
+  - throws a `KB::Error` exception if something went wrong
+- `contracts`
+  - returns all the KB::PetContract associated with this pet parent
+
+#### Assessment 📄
+
+`KB::Assessment` represents a read-only resource exposing:
+
+- `find`
+  - arg: `key` string
+  - returns: an Assessment instance when provided an existing key or raise `ActiveRecord::RecordNotFound`
+- `all`
+  - arg: `filters` hash of filters
+  - returns: an array of Assessment instances matching the filters
+
+#### Condition 🏷
+
+`KB::Condition` represents a read-only resource.
+
+#### Symptom 🩺
+
+`KB::Symptom` represents a read-only resource.
+
+#### Pet 🐶🐱
+
+`KB::Pet` represents a resource exposing:
+
+- `all`
+  - arg: `filters` hash of filters
+  - returns: an array of Pet instances matching the filters
+- `create`
+  - arg: `attributes` to initialize the entity
+  - returns: the raw attributes of the Pet instance
+  - throws an `KB::Error` exception if something went wrong
+- `find_or_create_by`
+  - arg: `attributes`, `additional_attributes` to look for or initialize the entity
+  - returns: look for a Pet matching the passed attributes or initialize and persist one with the given attributes and launching the block provided
+  - throws an `KB::Error` exception if something went wrong
+- `save!`
+  - persists (create or update) the entity to the Knowledge Base
+  - throws an `KB::Error` exception if something went wrong
+- `destroy!`
+  - deletes the entity in the Knowledge Base
+  - throws a `KB::Error` exception if something went wrong
+- `contracts`
+  - returns all the KB::PetContract associated with this pet
+- `upsert`
+  - updates KB:Pet if exists a Pet with same name for its PetParent
+  - creates a new KB:Pet if not exists a Pet with same name for its PetParent 
+
+#### PetContract 📝
+
+`KB::PetContract` represents a resource exposing:
+
+- `find`
+  - arg: `key` the key of the contract in the Knowledge Base
+  - returns the contract with the matching key
+  - throws an `KB::Error` or `KB::ResourceNotFound` exception if something went wrong
+- `find_by_contract_number`
+  - arg: `contract_number` the contract number to find
+  - returns the identified KB::PetContract
+  - throws an `KB::Error` or `KB::ResourceNotFound` exception if something went wrong
+- `create`
+  - arg: `attributes` to initialize the entity
+  - returns: the raw attributes of the PetContract instance
+  - throws an `KB::Error` exception if something went wrong
+- `save!`
+  - persists (create or update) the entity to the Knowledge Base
+  - throws an `KB::Error` exception if something went wrong
+
+#### Plan 🗺
+
+`KB::Plan` represents a resource exposing:
+
+- `all`
+  - returns: the array of available plans
+
+#### Breed
+
+```
+> KB Breed endpoint requires `locale` as param. By default is set to 'es-es' but can be override setting **KB_BREEDS_DEFAULT_LOCALE** ENV var
+```
+
+`KB::Breed` represents a resource exposing:
+
+- `all`
+  - arg: `filters` hash of filters
+  - returns: and array of Breed instances matching the filters
+- `dogs` (alias for all(species: 'dog'))
+  - arg: `filters` hash of filters
+  - returns: and array of Dog Breed instances matching the filters
+- `cats` (alias for all(species: 'cat'))
+  - arg: `filters` hash of filters
+  - returns: and array of Cat Breed instances matching the filters
+
+### Make an ActiveRecord wrap a KB entity
+
+The `KB::Concerns::AsKBWrapper` concern has been created in order to easily make an ActiveRecord model wrap a KB model.
+
+To use it:
+
+- include it into your wrapping model, define an attribute `kb_key` on your wrapping model
+- call `wrap_kb` with the wrapped KB model class (available option: `skip_callback`)
+
+You have then access to the wrapped model under `kb_model` and can delegate attributes to it, for instance:
+
+```ruby
+class User < ActiveRecord::Base
+  include KB::Concerns::AsKBWrapper
+
+  wrap_kb model: KB::PetParent
+
+  KB_DELEGATED_ATTRIBUTES = %i[email first_name].freeze
+
+  KB_DELEGATED_ATTRIBUTES.each do |attribute|
+    delegate attribute, to: :kb_model, prefix: false
+    delegate "#{attribute}=", to: :kb_model, prefix: false
+  end
+end
+
+user = User.create(first_name: 'Léo', email: 'leo@barkibu.com')
+p user.kb_model
+# => #<KB::PetParent: 0x000055fd72d32c30 key: "373ad90e-c2ce-46cb-9749-deb2b03be995", first_name: "Léo", ..., email: "leo@barkibu.com">
+```
+
+### Mock the API calls in test environment
+
+For testing purposes, you may want to fake Knowledge Base’s API calls. We provide a FakeApi app that you can use including the `kb-fake` gem in your dev/test dependencies.
+
+Add gem webmock and gem sinatra to your Gemfile to use the following configuration:
+
+```ruby
+    # ...
+
+    RSpec.configure do |config|
+        # ...
+        config.before(:all) do
+            stub_request(:any, /test_api_barkkb.com/).to_rack(KB::Fake::Api)
+        end
+
+        config.around(:each) do |example|
+            snapshot = KB::Fake::Api.snapshot()
+            stub_request(:any, /test_api_barkkb.com/).to_rack(KB::Fake::Api)
+            example.run
+            KB::Fake::Api.restore snapshot
+        end
+        # ...
+    end
+```
+
+Make sure to set the `KB_API_URL_TEMPLATE` to something that will match above the request interceptor, for instance: `http://test_api_barkkb.com/%{version}/%{entity}`
+
+You should be able to use the API seemlessly and the calls to the API will be intercepted and a local one used instead in a similar fashion to how ActiveRecord operations are wrapped into a transaction in a rails app with `use_transactional_fixtures` activated.
+
+## Development & Testing
+
+```bash
+    docker run -it --rm -v $(pwd):/app --workdir=/app ruby:2.6.5 bash
+
+    > bundle install
+    > rspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/kb. 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](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the KB project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/kb/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,28 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rspec/core/rake_task'
+require 'kb/version'
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc 'Build gem into the pkg directory'
+task :build do
+  FileUtils.rm_rf('pkg')
+  Dir['*.gemspec'].each do |gemspec|
+    system "gem build #{gemspec}"
+  end
+  FileUtils.mkdir_p('pkg')
+  FileUtils.mv(Dir['*.gem'], 'pkg')
+end
+
+desc 'Tags version, pushes to remote, and pushes gem'
+task release: :build do
+  sh 'git', 'tag', '-m', changelog, "v#{KB::VERSION}"
+  sh 'git push origin master'
+  sh "git push origin v#{KB::VERSION}"
+  sh 'ls pkg/*.gem | xargs -n 1 gem push'
+end
+
+def changelog
+  File.read('CHANGELOG.md').split(/##.*$\n/)[1].gsub("\n\n", "\n")
+end

data/barkibu-kb-fake.gemspec

@@ -0,0 +1,41 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kb/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'barkibu-kb-fake'
+  spec.version       = KB::VERSION
+  spec.authors       = ['Léo Figea']
+  spec.email         = ['leo@barkibu.com']
+
+  spec.summary       = "Barkibu's Knowledge Base Fake API"
+  spec.description   = "A fake API of Barkibu's Knowledge Base destined to be used in tests for application using the kb-ruby gem." # rubocop:disable Layout/LineLength
+  spec.homepage      = 'https://app.barkibu.com'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    # spec.metadata['allowed_push_host'] = 'http://mygemserver.com'
+
+    spec.metadata['homepage_uri'] = spec.homepage
+    # spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
+    # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+          'public gem pushes.'
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = `git ls-files -- lib | grep fake`.split("\n").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.6'
+
+  spec.add_runtime_dependency 'countries'
+  spec.add_runtime_dependency 'barkibu-kb', KB::VERSION
+  spec.add_runtime_dependency 'sinatra'
+  spec.add_runtime_dependency 'webmock'
+end

data/barkibu-kb.gemspec

@@ -0,0 +1,54 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kb/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'barkibu-kb'
+  spec.version       = KB::VERSION
+  spec.authors       = ['Léo Figea']
+  spec.email         = ['leo@barkibu.com']
+
+  spec.summary       = "Barkibu's Knowledge Base API sdk"
+  spec.description   = "A wrapper of Barkibu's Knowledge Base Endpoint to make those entities and their respective CRUD operations available to a ruby app" # rubocop:disable Layout/LineLength
+  spec.homepage      = 'https://app.barkibu.com'
+  spec.license       = 'MIT'
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  if spec.respond_to?(:metadata)
+    # spec.metadata['allowed_push_host'] = 'http://mygemserver.com'
+
+    spec.metadata['homepage_uri'] = spec.homepage
+    # spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
+    # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+  else
+    raise 'RubyGems 2.0 or newer is required to protect against ' \
+          'public gem pushes.'
+  end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.6'
+
+  spec.add_dependency 'dry-configurable', '~> 0.9'
+  spec.add_development_dependency 'bundler', '~> 1.17'
+  spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'rake', '>= 12.3.3'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'simplecov'
+  spec.add_runtime_dependency 'activemodel', '>= 4.0.2'
+  spec.add_runtime_dependency 'activerecord'
+  spec.add_runtime_dependency 'activesupport', '>= 3.0.0'
+  spec.add_runtime_dependency 'faraday'
+  spec.add_runtime_dependency 'faraday-http'
+  spec.add_runtime_dependency 'faraday_middleware'
+  spec.add_runtime_dependency 'i18n'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'barkibu-kb'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/docker-compose.yaml

@@ -0,0 +1,15 @@
+version: "3.0"
+services:
+  kb:
+    image: ruby:2.7.1-buster
+    working_dir: /app
+    volumes:
+      - .:/app
+      - bundle:/usr/local/bundle
+    environment: 
+      - KB_API_URL_TEMPLATE=$KB_API_URL_TEMPLATE
+      - KB_PARTNER_KEY=$KB_PARTNER_KEY
+      - KB_API_KEY=$KB_API_KEY
+
+volumes:
+  bundle:

data/lib/barkibu-kb-fake.rb

@@ -0,0 +1 @@
+require 'kb/fake'

data/lib/barkibu-kb.rb

@@ -0,0 +1,33 @@
+require'byebug'
+require 'kb/version'
+require 'active_model'
+require 'active_record'
+require 'active_support'
+require 'active_support/core_ext/array'
+require 'faraday'
+require 'faraday_middleware'
+require 'faraday/http'
+require 'dry/configurable'
+
+module KB
+  extend Dry::Configurable
+
+  setting :cache do
+    setting :instance, default: ActiveSupport::Cache::NullStore.new
+    setting :expires_in, default: 0
+  end
+
+  setting :log_level, default: :info
+end
+
+require 'kb/inflections'
+
+require 'kb/cache'
+require 'kb/client_resolver'
+require 'kb/errors'
+require 'kb/client'
+
+require 'kb/concerns'
+require 'kb/models'
+
+require 'kb/validators'

data/lib/kb/cache.rb

@@ -0,0 +1,23 @@
+module KB
+  class Cache
+    class << self
+      def delete(key)
+        instance.delete(key)
+      end
+
+      def fetch(key, &block)
+        instance.fetch(key, expires_in: cache_expiration, &block)
+      end
+
+      private
+
+      def instance
+        KB.config.cache.instance
+      end
+
+      def cache_expiration
+        KB.config.cache.expires_in.to_f
+      end
+    end
+  end
+end

data/lib/kb/client.rb

@@ -0,0 +1,85 @@
+module KB
+  class Client
+    attr_reader :api_key, :base_url
+
+    def initialize(base_url, api_key: ENV['KB_API_KEY'])
+      @api_key = api_key
+      @base_url = base_url
+    end
+
+    def request(sub_path, filters: nil, method: :get)
+      return connection.public_send(method, sub_path, filters).body if method != :get
+
+      cache_key = "#{@base_url}/#{sub_path}/#{(filters || {}).sort.to_h}"
+      KB::Cache.fetch(cache_key) do
+        connection.public_send(method, sub_path, filters).body
+      end
+    end
+
+    def all(filters = {})
+      cache_key = "#{@base_url}/#{filters.sort.to_h}"
+
+      KB::Cache.fetch(cache_key) do
+        connection.get('', attributes_case_transform(filters)).body
+      end
+    end
+
+    def find(key, params = {})
+      raise Faraday::ResourceNotFound, {} if key.blank?
+
+      KB::Cache.fetch("#{@base_url}/#{key}") do
+        connection.get(key, attributes_case_transform(params)).body
+      end
+    end
+
+    def create(attributes)
+      connection.post('', attributes_to_json(attributes)).body
+    end
+
+    def update(key, attributes)
+      KB::Cache.delete("#{@base_url}/#{key}")
+      connection.patch(key.to_s, attributes_to_json(attributes)).body
+    end
+
+    def destroy(key)
+      KB::Cache.delete("#{@base_url}/#{key}")
+      connection.delete(key.to_s).body
+    end
+
+    def upsert(attributes)
+      connection.put('', attributes_to_json(attributes)).body
+    end
+
+    private
+
+    def headers
+      {
+        'Content-Type': 'application/json',
+        'x-api-key': api_key
+      }
+    end
+
+    def attributes_case_transform(attributes)
+      attributes.transform_keys do |key|
+        key.to_s.camelize(:lower)
+      end
+    end
+
+    def attributes_to_json(attributes)
+      attributes_case_transform(attributes).to_json
+    end
+
+    def connection
+      @connection ||= Faraday.new(url: base_url, headers: headers) do |conn|
+        conn.response :json
+        conn.response :raise_error
+        if KB.config.log_level == :debugger
+          conn.response :logger do |logger|
+            logger.filter(/(X-api-key:\s)("\w+")/, '\1[API_KEY_SCRUBBED]')
+          end
+        end
+        conn.adapter :http
+      end
+    end
+  end
+end

data/lib/kb/client_resolver.rb

@@ -0,0 +1,62 @@
+module KB
+  class ClientResolver
+    class << self
+      def consultation
+        call :petfamily, :consultations, :v1
+      end
+
+      def admin
+        call :petfamily, :admin
+      end
+
+      def pet_parent
+        call :petfamily, :petparents
+      end
+
+      def pet
+        call :petfamily, :pets
+      end
+
+      def pet_contract
+        call :petfamily, :petcontracts
+      end
+
+      def breed
+        call :petfamily, :breeds
+      end
+
+      def plan
+        call :petfamily, :plans
+      end
+
+      def product
+        call :petfamily, :products
+      end
+
+      def hubspot
+        call :petfamily, :hubspot
+      end
+
+      def call(*args, &block)
+        new(*args, &block).call
+      end
+    end
+
+    attr_reader :template, :bounded_context, :entity, :version
+
+    def initialize(bounded_context, entity, version = 'v1', template: ENV['KB_API_URL_TEMPLATE'])
+      @bounded_context = bounded_context
+      @entity = entity
+      @version = version
+      @template = template
+    end
+
+    def call
+      KB::Client.new base_url
+    end
+
+    def base_url
+      format(template, bounded_context: bounded_context, entity: entity, version: version).gsub('..', '.')
+    end
+  end
+end

data/lib/kb/concerns/as_kb_wrapper.rb

@@ -0,0 +1,67 @@
+module KB
+  module Concerns
+    module AsKBWrapper
+      extend ActiveSupport::Concern
+
+      included do
+        attr_writer :kb_model
+
+        def save_underlying_kb_entity!
+          kb_model.save!
+          self.kb_key = kb_model.key if kb_model.key.present?
+        end
+
+        def destroy_underlying_kb_entity
+          kb_model.destroy!
+        end
+
+        def reload(**options)
+          @kb_model = nil
+          super(**options)
+        end
+      end
+
+      # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Metrics/BlockLength
+      class_methods do
+        def wrap_kb(model:, skip_callback: false)
+          before_save :save_underlying_kb_entity! unless skip_callback
+          before_destroy :destroy_underlying_kb_entity unless skip_callback
+
+          define_method(:kb_model) do
+            underlying_kb_entity = @kb_model
+
+            if underlying_kb_entity.blank?
+              underlying_kb_entity = begin
+                model.find kb_key
+              rescue KB::ResourceNotFound
+                model.new
+              end
+
+              @kb_model = underlying_kb_entity
+            end
+
+            underlying_kb_entity
+          end
+
+          singleton_class.instance_eval do
+            define_method(:kb_find_by) do |**attributes|
+              kb_model = model.all(attributes).first
+              return nil if kb_model.nil?
+
+              local_model = find_by(kb_key: kb_model.key)
+              return nil if local_model.nil?
+
+              local_model.kb_model = kb_model
+              local_model
+            end
+          end
+        end
+
+        def kb_find_by!(**attributes)
+          kb_find_by(attributes).presence || raise(ActiveRecord::RecordNotFound)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Metrics/BlockLength
+    end
+  end
+end

data/lib/kb/concerns.rb

@@ -0,0 +1 @@
+require 'kb/concerns/as_kb_wrapper'