dialers 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3978ac1bde74537904eb9303ca9110fb6d602527
+  data.tar.gz: d3d1ab7abdddaee79b6f3fd6c81b2969d886c412
+SHA512:
+  metadata.gz: 27e135965acf52401317d38637ec87e08d82fd1afdd825f497cd9e0c63c64572566a00aa29929975167fca8eaba0cdf7081b4399ce5d30a8f5c46e45d4900f60
+  data.tar.gz: 97446946876217282580984376a6fa36d71c09e31999fa0ffd18ed061021e948d490e0de54563ff78b98b12a9f229f0f884fe1068a7938165535422dbd6f662c

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.rbenv-vars

data/.rbenv-vars-example

@@ -0,0 +1,4 @@
+TWITTER_CONSUMER_KEY=
+TWITTER_CONSUMER_SECRET=
+TWITTER_TOKEN=
+TWITTER_TOKEN_SECRET=

data/.rspec

@@ -0,0 +1,5 @@
+--color
+--require spec_helper
+--require rspec/legacy_formatters
+--format=doc
+--format=Nc

data/.rubocop.yml

@@ -0,0 +1,89 @@
+AllCops:
+  Exclude:
+    - bin/**/*
+    - tmp/**/*
+
+Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/HashSyntax:
+  EnforcedStyle: ruby19
+  UseHashRocketsWithSymbolValues: true
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/AccessorMethodName:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/IfUnlessModifier:
+  Enabled: false
+
+Style/NegatedIf:
+  Enabled: false
+
+Style/AlignParameters:
+  EnforcedStyle: with_fixed_indentation
+
+Style/Lambda:
+  Enabled: false
+
+Style/BracesAroundHashParameters:
+  Enabled: false
+
+Style/PredicateName:
+  NamePrefixBlacklist: []
+
+Style/ClassAndModuleCamelCase:
+  Enabled: false
+
+Style/GlobalVars:
+  Enabled: false
+
+Style/WordArray:
+  Enabled: false
+
+Style/AsciiComments:
+  Enabled: false
+
+Style/MultilineBlockChain:
+  Enabled: false
+
+Style/EachWithObject:
+  Enabled: false
+
+Style/MultilineBlockLayout:
+  Enabled: false
+
+Style/SpaceAroundBlockParameters:
+  Enabled: false
+
+Style/BlockComments:
+  Enabled: false
+
+Style/ModuleFunction:
+  Enabled: false
+
+Style/RaiseArgs:
+  EnforcedStyle: compact
+
+Lint/AmbiguousOperator:
+  Enabled: false
+
+Lint/EndAlignment:
+  AlignWith: "variable"
+
+Metrics/LineLength:
+  Max: 100
+
+Metrics/AbcSize:
+  Enabled: False
+
+Metrics/ClassLength:
+  Max: 100

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.0.0
+before_install: gem install bundler -v 1.10.5

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in dialers.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,16 @@
+guard :rspec, cmd: "bin/rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 juliogarciag
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/NOTES.md

@@ -0,0 +1,60 @@
+1. Example with Twitter
+
+```ruby
+# This example requires the gem simple_oauth
+module Twitter
+  class ApiCaller < Dialers::Caller
+    BASE_URL = "https://api.twitter.com/1.1/"
+    CONSUMER_KEY = ENV["TWITTER_CONSUMER_KEY"]
+    CONSUMER_SECRET = ENV["TWITTER_CONSUMER_SECRET"]
+    TOKEN = ENV["TWITTER_TOKEN"]
+    TOKEN_SECRET= ENV["TWITTER_TOKEN_SECRET"]
+
+    setup_api(url: BASE_URL) do |faraday|
+      faraday.request :json
+      faraday.request :oauth,
+        consumer_key: CONSUMER_KEY,
+        consumer_secret: CONSUMER_SECRET,
+        token: TOKEN,
+        token_secret: TOKEN_SECRET
+      faraday.response :json
+      faraday.adapter :net_http
+    end
+
+    short_circuits.add(
+      if: -> (response) { Dialers::Status.new(response.status).server_error? },
+      do: -> (response) { fail Dialers::ServerError.new(response) }
+    )
+
+    short_circuits.push(
+      if: -> (response) { Dialers::Status.new(response.status).is?(401) },
+      do: -> (response) { fail Dialers::UnauthorizedError.new(response) }
+    )
+
+    short_circuits.add(
+      if: -> { |response| Dialers::Status.new(response.status).is?(404) },
+      do: -> { |response| fail Dialers::NotFoundError.new(response) }
+    )
+  end
+
+  class Tweet
+    attr_accessor :created_at, :text
+  end
+
+  class User
+    attr_accessor :screen_name, :profile_image_url
+  end
+
+  class Api < Dialers::Wrapper
+    api_caller { ApiCaller.new }
+
+    def get_user_timeline
+      api_caller.get("statuses/user_timeline.json").transform_to_many(Tweet)
+    end
+
+    def get_user
+      api_caller.get("account/verify_credentials.json").transform_to_one(User)
+    end
+  end
+end
+```

data/README.md

@@ -0,0 +1,143 @@
+# Dialers
+
+Dialers is a gem that allows to easily create wrappers over external HTTP apis using [Faraday](https://github.com/lostisland/faraday).
+
+## Installation
+
+Add this line to your Gemfile:
+
+```ruby
+gem "dialers"
+```
+
+And then execute:
+
+    $ bundle
+
+Additionally, if you want to use a Faraday adapter different from the default one (`net_http`, based on the built-in ruby library), you have to install the gem for that. For example, to use [patron](https://github.com/toland/patron) you have to add `gem "patron"` to your Gemfile. For simplicity, this readme will use the default `net_http` adapter.
+
+## Usage
+
+We will use the Github API public part as a example. First, you need at least two classes: one to keep your api methods and another one to keep the api connection configuration. Let's start with this:
+
+```ruby
+module Github
+  class Api < Dialers::ApiWrapper
+  end
+
+  class ApiCaller < Dialers::Caller
+  end
+end
+```
+
+Now, let's configure our github api. It's important to note that this configuration is the same that Faraday uses (indeed, it's passed to Faraday as it is):
+
+```ruby
+module Github
+  class ApiCaller < Dialers::Caller
+    TIMEOUT_IN_SECONDS = 5
+    GITHUB_API_URL = "https://api.github.com"
+
+    setup_api(url: GITHUB_API_URL) do |faraday|
+      faraday.request :json
+      faraday.request :request_headers, accept: "application/vnd.github.v3+json"
+      faraday.response :json
+      faraday.adapter :net_http
+      faraday.options.timeout = TIMEOUT_IN_SECONDS
+      faraday.options.open_timeout = TIMEOUT_IN_SECONDS
+    end
+  end
+end
+```
+
+If you want to know more about how to configure Faraday to some different and more complex use cases, please check the [examples directory](examples/). Now that the configuration is over, let's plug the caller into the wrapper to be able to create some methods.
+
+```ruby
+module Github
+  class Api < Dialers::ApiWrapper
+    api_caller { Github::ApiCaller }
+
+    def user_repos(username)
+      api_caller.get("users/#{username}/repos").as_received
+    end
+  end
+end
+```
+
+Let's try this:
+
+```ruby
+github = Github::Api.new
+github.user_repos("rails")
+# => [ { ... }] # An enormous array of hashes
+```
+
+Now, this sucks for us because we don't have any kind of schema nor classes here. Let's add something to organize this response:
+
+```ruby
+module Github
+  class Repository
+    attr_accessor :id, :name, :description, :language
+  end
+
+  class Api < Dialers::ApiWrapper
+    api_caller { Github::ApiCaller }
+
+    def user_repos(username)
+      api_caller.get("users/#{username}/repos").transform_to_many(Github::Repository)
+    end
+  end
+end
+```
+
+Using `transform_to_many` we mapped the response body to many `Github::Repository` objects. Let's try now:
+
+```ruby
+github = Github::Api.new
+repositories = github.user_repos("rails")
+repositories.first.name # maybe Rails
+```
+
+You can use `post`, `put`, `patch`, `options`, `get` and `head` on the callers. You can use `transform_to_one` to make just one object and you can pass a hash to decide which object to instantiate depending on the response's status. For more info, you can check out [the caller's documentation](http://www.rubydoc.info/github/platanus/dialers/master/Dialers/Caller).
+
+## Some Rails Nice Things
+
+***NOTE: This a thing we want to make. It's not done yet but we want it to be this way***
+
+In Rails, you can use the next command to generate a dialer wrapper:
+
+```bash
+$ rails g dialers:api anexternalservice
+```
+
+This will generate the following structure:
+
+```
+dialers/
+  anexternalservice/
+    api.rb
+    api_caller.rb
+```
+
+Everything else is the same. This is just a proposal for a organization friendly to Rails. But, if you want, you can use any class organization you want.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake false` 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).
+
+To run the examples in the examples directory you have to setup some environment variables as defined in `.rbenv-vars-example` and run the examples like this:
+
+```
+$ ruby -Ilib examples/github/usage.rb
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/platanus/dialers.
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/bin/_guard-core

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application '_guard-core' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('guard', '_guard-core')

data/bin/console

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "dialers"
+require "pry"
+
+Pry.start

data/bin/guard

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'guard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('guard', 'guard')

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/bin/setup

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