jeckle 0.4.0.beta3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: daea79214eac076d0f45217ccad97e299f0b8ed4
-  data.tar.gz: 815eb79a5058729ef025476a438cff1a5fc358c4
+SHA256:
+  metadata.gz: 187c3bfe2db7cab76746126db6fbf418de6068d087adeb0c817d2ded6f1d4462
+  data.tar.gz: e2aa04caf4838dd135c1c4cb9a70db7429975466fa3db37cf4745a6febba541d
 SHA512:
-  metadata.gz: d7299c4462181501c834c7b33cfde8d06beca7ad21611c87a2b173070e2e9f864b3f01977045ee914cb54efe71c8c913e6fdce6021669c37735303144688ef17
-  data.tar.gz: 83388f41b76f585a801c13d7f4742237448f6982c44a5210abc5c0e3f37ba1a6172d74aa65dc1eefb82f0a7e3002337536c89961c309f0a0b78134efd31aff44
+  metadata.gz: 5ce3a1792ce54a89573a6a0be1a72d85f4381f7542883847ff0b7e5200309ec9388b2dfb45923e5133aa0c3c1c83b81e2df78030a276bbc83d07869699a9ff57
+  data.tar.gz: 3f181d2afe18db62be11d4d5faffa47c1e1f4532029d7704d46cf2b29969e1b15bd63ce18563ccad8c5c3796fab2cd9a504a5c77478917c24a2337a55661614f

data/README.md

@@ -1,8 +1,6 @@
 # Jeckle
 
-[![Build Status](https://travis-ci.org/tomas-stefano/jeckle.svg?branch=master)](https://travis-ci.org/tomas-stefano/jeckle)
-[![Code Climate](https://codeclimate.com/github/tomas-stefano/jeckle.png)](https://codeclimate.com/github/tomas-stefano/jeckle)
-[![Test Coverage](https://codeclimate.com/github/tomas-stefano/jeckle/coverage.png)](https://codeclimate.com/github/tomas-stefano/jeckle)
+[![CI](https://github.com/tomas-stefano/jeckle/actions/workflows/ci.yml/badge.svg)](https://github.com/tomas-stefano/jeckle/actions/workflows/ci.yml)
 
 Wrap APIs with easiness and flexibility.
 
@@ -20,53 +18,148 @@ Let third party APIs be Heckle for your app's Jeckle.
 
 Add this line to your application's Gemfile:
 
-    gem 'jeckle'
+```ruby
+gem 'jeckle'
+```
 
 And then execute:
 
-    $ bundle
+```sh
+$ bundle
+```
 
-### For Rails applications
+## Usage
 
-We recommend to create a initializer:
+### Configuring an API
 
-```ruby
-# config/initializers/jeckle.rb
+Let's say you'd like to connect your app to Dribbble.com - a community of designers sharing screenshots of their work, process, and projects.
 
+First, you would need to configure the API:
+
+```ruby
 Jeckle.configure do |config|
-  config.register :some_service do |api|
-    api.base_uri = 'http://api.someservice.com'
-    api.headers = {
-      'Accept' => 'application/json'
-    }
-    api.namespaces = { prefix: 'api', version: 'v1' }
-    api.logger = Rails.logger
-    api.read_timeout = 5
+  config.register :dribbble do |api|
+    api.base_uri = 'http://api.dribbble.com'
+    api.middlewares do
+      response :json
+    end
   end
 end
 ```
 
-And then put your API stuff scoped inside a `services` folder:
+### Mapping resources
+
+Following the previous example, Dribbble.com consists of pieces of web designers work called "Shots". Each shot has the attributes `id`, `name`, `url` and `image_url`. A Jeckle resource representing Dribbble's shots would be something like this:
 
 ```ruby
-# app/services/some_service/models/my_resource.rb
+class Shot
+  include Jeckle::Resource
+
+  api :dribbble
+
+  attribute :id, Integer
+  attribute :name, String
+  attribute :url, String
+  attribute :image_url, String
+end
+```
+
+### Fetching data
 
-module SomeService
-  module Models
-    class MyResource
-      include Jeckle::Resource
+The resource class allows us to search shots through HTTP requests to the API, based on the provided information. For example, we can find a specific shot by providing its id to the `find` method:
 
-      api :some_service
+```ruby
+# GET http://api.dribbble.com/shots/1600459
+shot = Shot.find 1600459
+```
+
+That will return a `Shot` instance, containing the shot info:
+
+```ruby
+shot.id
+=> 1600459
+
+shot.name
+=> "Daryl Heckle And Jeckle Oates"
+
+shot.image_url
+=> "https://d13yacurqjgara.cloudfront.net/users/85699/screenshots/1600459/daryl_heckle_and_jeckle_oates-dribble.jpg"
+```
+
+You can also look for many shots matching one or more attributes, by using the `search` method:
+
+```ruby
+# GET http://api.dribbble.com/shots?name=avengers
+shots = Shot.search name: 'avengers'
+```
 
-      attribute :id
+### Attribute Aliasing
+
+Sometimes you want to call the API's attributes something else, either because their names aren't very concise or because they're out of you app's convention. If that's the case, you can add an `as` option:
+
+```ruby
+attribute :thumbnailSize, String, as: :thumbnail_size
+```
+
+Both mapping will work:
+
+```ruby
+shot.thumbnailSize
+=> "50x50"
+
+shot.thumbnail_size
+=> "50x50"
+```
+
+We're all set! Now we can expand the mapping of our API, e.g to add ability to search Dribbble Designer directory by adding Designer class, or we can expand the original mapping of Shot class to include more attributes, such as tags or comments.
+
+### Error Handling
+
+Jeckle provides a built-in Faraday middleware that automatically raises typed errors for HTTP error responses. Enable it in your API configuration:
+
+```ruby
+Jeckle.configure do |config|
+  config.register :dribbble do |api|
+    api.base_uri = 'http://api.dribbble.com'
+    api.middlewares do
+      response :json
+      response :jeckle_raise_error
     end
   end
 end
 ```
 
+Then rescue specific errors in your code:
+
+```ruby
+begin
+  Shot.find 999
+rescue Jeckle::NotFoundError => e
+  puts "Not found: #{e.message} (status: #{e.status})"
+rescue Jeckle::ClientError => e
+  puts "Client error: #{e.status}"
+rescue Jeckle::ServerError => e
+  puts "Server error: #{e.status}"
+rescue Jeckle::HTTPError => e
+  puts "HTTP error: #{e.status}"
+end
+```
+
+The error hierarchy:
+
+- `Jeckle::Error` — base error
+  - `Jeckle::ConnectionError` — network connectivity errors
+  - `Jeckle::TimeoutError` — request timeout errors
+  - `Jeckle::HTTPError` — HTTP errors (has `status` and `body` attributes)
+    - `Jeckle::ClientError` — 4xx errors
+      - `BadRequestError` (400), `UnauthorizedError` (401), `ForbiddenError` (403), `NotFoundError` (404), `UnprocessableEntityError` (422), `TooManyRequestsError` (429)
+    - `Jeckle::ServerError` — 5xx errors
+      - `InternalServerError` (500), `ServiceUnavailableError` (503)
+
+## Examples
+
+You can see more examples here: [https://github.com/tomas-stefano/jeckle/tree/master/examples](https://github.com/tomas-stefano/jeckle/tree/master/examples)
+
 ## Roadmap
 
-- Faraday middleware abstraction
-- Per action API
-- Comprehensive restful actions
-- Testability
+Follow [GitHub's milestones](https://github.com/tomas-stefano/jeckle/milestones)

data/lib/jeckle/api.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jeckle
   class API
     attr_accessor :logger
@@ -10,14 +12,14 @@ module Jeckle
         conn.params = params
         conn.response :logger, logger
 
-        conn.basic_auth basic_auth[:username], basic_auth[:password] if basic_auth
-        conn.instance_exec &@middlewares_block if @middlewares_block
+        conn.request :authorization, :basic, basic_auth[:username], basic_auth[:password] if basic_auth
+        conn.instance_exec(&@middlewares_block) if @middlewares_block
       end
     end
 
     def basic_auth=(credential_params)
-      [:username, :password].all? do |key|
-        credential_params.has_key? key
+      %i[username password].all? do |key|
+        credential_params.key? key
       end or raise Jeckle::NoUsernameOrPasswordError, credential_params
 
       @basic_auth = credential_params

data/lib/jeckle/attribute_aliasing.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Jeckle
+  module AttributeAliasing
+    def attribute(name, coercion, options = {})
+      if (custom_name = options.delete(:as))
+        super(custom_name, coercion, options)
+
+        alias_method name, custom_name
+        alias_method :"#{name}=", :"#{custom_name}="
+      else
+        super
+      end
+    end
+  end
+end

data/lib/jeckle/errors.rb

@@ -1,29 +1,115 @@
+# frozen_string_literal: true
+
 module Jeckle
+  class Error < StandardError; end
+
+  class ConnectionError < Error; end
+  class TimeoutError < Error; end
+
+  class HTTPError < Error
+    attr_reader :status, :body
+
+    def initialize(message = nil, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+  end
+
+  class ClientError < HTTPError; end
+
+  class BadRequestError < ClientError
+    DEFAULT_STATUS = 400
+
+    def initialize(message = 'Bad Request', status: DEFAULT_STATUS, body: nil)
+      super
+    end
+  end
+
+  class UnauthorizedError < ClientError
+    DEFAULT_STATUS = 401
+
+    def initialize(message = 'Unauthorized', status: DEFAULT_STATUS, body: nil)
+      super
+    end
+  end
+
+  class ForbiddenError < ClientError
+    DEFAULT_STATUS = 403
+
+    def initialize(message = 'Forbidden', status: DEFAULT_STATUS, body: nil)
+      super
+    end
+  end
+
+  class NotFoundError < ClientError
+    DEFAULT_STATUS = 404
+
+    def initialize(message = 'Not Found', status: DEFAULT_STATUS, body: nil)
+      super
+    end
+  end
+
+  class UnprocessableEntityError < ClientError
+    DEFAULT_STATUS = 422
+
+    def initialize(message = 'Unprocessable Entity', status: DEFAULT_STATUS, body: nil)
+      super
+    end
+  end
+
+  class TooManyRequestsError < ClientError
+    DEFAULT_STATUS = 429
+
+    def initialize(message = 'Too Many Requests', status: DEFAULT_STATUS, body: nil)
+      super
+    end
+  end
+
+  class ServerError < HTTPError; end
+
+  class InternalServerError < ServerError
+    DEFAULT_STATUS = 500
+
+    def initialize(message = 'Internal Server Error', status: DEFAULT_STATUS, body: nil)
+      super
+    end
+  end
+
+  class ServiceUnavailableError < ServerError
+    DEFAULT_STATUS = 503
+
+    def initialize(message = 'Service Unavailable', status: DEFAULT_STATUS, body: nil)
+      super
+    end
+  end
+
+  # Legacy errors (kept for backwards compatibility)
   class ArgumentError < ::ArgumentError; end
 
   class NoSuchAPIError < ArgumentError
     def initialize(api)
-      message = %{The API name '#{api}' doesn't exist in Jeckle definitions.
+      message = %(The API name '#{api}' doesn't exist in Jeckle definitions.
 
         Heckle: - Hey chum, what we can do now?
         Jeckle: - Old chap, you need to put the right API name!
         Heckle: - Hey pal, tell me the APIs then!
         Jeckle: - Deal the trays, old thing: #{Jeckle::Setup.registered_apis.keys}.
-      }
+      )
 
-      super message
+      super(message)
     end
   end
 
   class NoUsernameOrPasswordError < ArgumentError
-    def initialize(credentials)
-      message = %{No such keys "username" and "password" on `basic_auth` definition"
+    def initialize(_credentials)
+      message = %(No such keys "username" and "password" on `basic_auth` definition"
 
         Heckle: - Hey chum, what we can do now?
         Jeckle: - Old chap, you need to define a username and a password for basic auth!
-      }
+      )
 
-      super message
+      super(message)
     end
   end
 end

data/lib/jeckle/http.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jeckle
   module HTTP
     def self.included(base)
@@ -11,8 +13,6 @@ module Jeckle
         end
       end
 
-      # @public
-      #
       # The name of the resource that Jeckle uses to make the request
       #
       # @example
@@ -41,23 +41,6 @@ module Jeckle
         @resource_name ||= model_name.element.pluralize
       end
 
-      # @public
-      #
-      # Overwritten the resource name without write the resource name method.
-      #
-      # @example
-      #
-      #   module OtherApi
-      #     class Project
-      #       include Jeckle::Resource
-      #       resource 'projects.json'
-      #     end
-      #   end
-      #
-      def resource(jeckle_resource_name)
-        @resource_name = jeckle_resource_name
-      end
-
       # The API name that Jeckle uses to find all the api settings like domain, headers, etc.
       #
       # @example
@@ -75,14 +58,14 @@ module Jeckle
       #
       def api(registered_api_name)
         api_mapping[:default_api] = Jeckle::Setup.registered_apis.fetch(registered_api_name)
-      rescue KeyError => e
+      rescue KeyError
         raise Jeckle::NoSuchAPIError, registered_api_name
       end
 
       # @deprecated Please use {#api} instead
       #
       def default_api(registered_api_name)
-        warn "[DEPRECATION] `default_api` is deprecated.  Please use `api` instead."
+        warn '[DEPRECATION] `default_api` is deprecated. Please use `api` instead.'
         api(registered_api_name)
       end
 
@@ -91,14 +74,8 @@ module Jeckle
       end
 
       def run_request(endpoint, options = {})
-        request = Jeckle::Request.run api_mapping[:default_api], endpoint, options
-
-        if logger = api_mapping[:default_api].logger
-          logger.debug("#{self} Response: #{request.response.body}")
-        end
-
-        request
+        Jeckle::Request.run api_mapping[:default_api], endpoint, options
       end
     end
   end
-end
+end

data/lib/jeckle/middleware/raise_error.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Jeckle
+  module Middleware
+    class RaiseError < Faraday::Middleware
+      STATUS_MAP = {
+        400 => Jeckle::BadRequestError,
+        401 => Jeckle::UnauthorizedError,
+        403 => Jeckle::ForbiddenError,
+        404 => Jeckle::NotFoundError,
+        422 => Jeckle::UnprocessableEntityError,
+        429 => Jeckle::TooManyRequestsError,
+        500 => Jeckle::InternalServerError,
+        503 => Jeckle::ServiceUnavailableError
+      }.freeze
+
+      def on_complete(env)
+        status = env.status
+
+        return if status < 400
+
+        error_class = STATUS_MAP.fetch(status) do
+          status < 500 ? Jeckle::ClientError : Jeckle::ServerError
+        end
+
+        raise error_class.new(env.reason_phrase, status: status, body: env.body)
+      end
+    end
+  end
+end
+
+Faraday::Response.register_middleware(jeckle_raise_error: Jeckle::Middleware::RaiseError)

data/lib/jeckle/model.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
+
 module Jeckle
   module Model
     def self.included(base)
-      base.send :include, ActiveModel::Validations
-      base.send :include, Virtus.model
+      base.include ActiveModel::Validations
+      base.include Virtus.model
     end
   end
 end

data/lib/jeckle/request.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jeckle
   class Request
     attr_reader :api, :body, :headers, :method, :params, :response, :endpoint
@@ -6,17 +8,28 @@ module Jeckle
       @api = api
 
       @method  = options.delete(:method) || :get
-      @body    = options.delete(:body) if %w(post put).include?(method.to_s)
+      @body    = options.delete(:body) if %w[post put patch].include?(method.to_s)
       @headers = options.delete(:headers)
 
+      if options[:params].nil? && options.size.positive?
+        warn %([DEPRECATION] Sending URL params mixed with options hash is deprecated.
+        Instead of doing this:
+          run_request 'cars/search', id: id, method: :get
+        Do this:
+          run_request 'cars/search', params: { id: id }, method: :get)
+
+        @params = options
+      else
+        @params = options.delete(:params) || {}
+      end
+
       @endpoint = endpoint
-      @params = options
 
       @response = perform_api_request
     end
 
-    def self.run(*args)
-      new *args
+    def self.run(api, endpoint, options = {})
+      new(api, endpoint, options)
     end
 
     private

data/lib/jeckle/resource.rb

@@ -1,11 +1,15 @@
+# frozen_string_literal: true
+
 module Jeckle
   module Resource
     def self.included(base)
-      base.send :include, ActiveModel::Naming
+      base.include ActiveModel::Naming
+
+      base.include Jeckle::Model
+      base.include Jeckle::HTTP
+      base.include Jeckle::RESTActions
 
-      base.send :include, Jeckle::Model
-      base.send :include, Jeckle::HTTP
-      base.send :include, Jeckle::RESTActions
+      base.extend Jeckle::AttributeAliasing
     end
   end
 end

data/lib/jeckle/rest_actions.rb

@@ -1,106 +1,27 @@
+# frozen_string_literal: true
+
 module Jeckle
   module RESTActions
     def self.included(base)
-      base.send :extend, Jeckle::RESTActions::Collection
+      base.extend Jeckle::RESTActions::Collection
     end
 
     module Collection
-      # @public
-      #
-      # The root name that Jeckle will parse the <b>response</b>. Default is <b>false</b>.
-      #
-      # @example
-      #
-      #   module Dribble
-      #     class Shot
-      #       include Jeckle::Resource
-      #       root collection: true, member: true
-      #     end
-      #   end
-      #
-      #   Shot.collection_root_name # => Will parse the root node as 'shots'
-      #   Shot.member_root_name # => Will parse the root node as 'shot'
-      #
-      #  Sometimes that are APIs you need to fetch /projects, BUT the root node is extremely different from the resource name.
-      #
-      #   module OtherApi
-      #     class Project
-      #       include Jeckle::Resource
-      #       api :my_api
-      #       root collection: 'awesome-projects', member: 'awesome-project'
-      #     end
-      #   end
-      #
-      def root(options={})
-        @collection_root_name = find_root_name(options[:collection], :pluralize)
-        @member_root_name     = find_root_name(options[:member], :singularize)
-      end
-
-      # @public
-      #
-      # Member action that requests for the resource using the resource name
-      #
-      #  @example
-      #
-      #     Post.find(1) # => posts/1
-      #
       def find(id)
-        endpoint   = "#{resource_name}/#{id}"
-        response   = run_request(endpoint).response.body
-        attributes = parse_response(response, member_root_name)
+        endpoint = "#{resource_name}/#{id}"
+        attributes = run_request(endpoint).response.body
 
-        new(attributes)
+        new attributes
       end
 
-      # @public
-      #
-      # Collection action that requests for the resource using the resource name
-      #
-      #  @example
-      #
-      #     Post.search({ status: 'published' }) # => posts/?status=published
-      #     Post.where({ status: 'published' }) # => posts/?status=published
-      #
       def search(params = {})
-        request    = run_request(resource_name, params)
-        response   = request.response
-        collection = parse_response(response.body, collection_root_name)
+        custom_resource_name = params.delete(:resource_name) if params.is_a?(Hash)
 
-        CollectionResponse.new(collection, context: self, response: response)
-      end
-      alias :where :search
-
-      # @private
-      #
-      def parse_response(response, root_name)
-        if root_name
-          response[root_name]
-        else
-          response
-        end
-      end
-
-      # @private
-      #
-      def find_root_name(root_name, root_method)
-        return root_name if root_name.is_a?(String)
-
-        if root_name
-          model_name.element.send(root_method)
-        end
-      end
-
-      # @private
-      #
-      def collection_root_name
-        @collection_root_name
-      end
+        response   = run_request(custom_resource_name || resource_name, params: params).response.body || []
+        collection = response.is_a?(Array) ? response : response[resource_name]
 
-      # @private
-      #
-      def member_root_name
-        @member_root_name
+        Array(collection).collect { |attrs| new attrs }
       end
     end
   end
-end
+end

data/lib/jeckle/setup.rb

@@ -1,6 +1,8 @@
+# frozen_string_literal: true
+
 module Jeckle
   class Setup
-    # Register apis, providing all the configurations to it.
+    # Register APIs, providing all the configurations to it.
     #
     # @example
     #

data/lib/jeckle/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Jeckle
-  VERSION = '0.4.0.beta3'
+  VERSION = '0.5.0'
 end