atum 0.5.0

data/lib/atum/generation/generators/views/module.erb

@@ -0,0 +1,104 @@
+# encoding: utf-8
+#
+# WARNING: Do not edit by hand, this file was generated by Atum:
+#
+#   https://github.com/gocardless/atum
+#
+require 'atum'
+require 'uri'
+
+# Ensure module namespacing is set up
+<% @module_name.split("::").size.times do |i| %>
+module <%= @module_name.split("::")[0..i].join("::") %>; end
+<% end %>
+
+version_file = '<%= @module_name.downcase.underscore.split("/").last %>/version'
+if File.file?(version_file)
+require version_file
+else
+<%= "#{@module_name}::VERSION" %> = ''
+end
+require_relative '<%= @module_name.downcase.underscore.split("/").last %>/client'
+<% @resources.each do |resource| %>
+require_relative '<%= @module_name.downcase.underscore.split("/").last %>/resources/<%= resource.name.underscore %>'
+<% end %>
+
+module <%= @module_name %>
+  extend Forwardable
+
+  <% @resources.each do |resource| %>
+  def self.<%= resource.name %>(*args)
+    self.client.<%= resource.name %>(*args)
+  end
+  <% end %>
+
+  # Get a Client configured to use HTTP Basic authentication.
+  #
+  # @param api_key [String] The API key to use when connecting.
+  # @param options [Hash<Symbol,String>] Optionally, custom settings
+  #   to use with the client.  Allowed options are `default_headers`,
+  #   `cache`, `user` and `url`.
+  # @return [Client] A client configured to use the API with HTTP Basic
+  #   authentication.
+  def self.connect(api_key, options = nil)
+    options = self.custom_options(options)
+    uri = URI.parse(options[:url])
+    uri.user = options.fetch(:user, 'user').gsub('@', '%40')
+    uri.password = api_key
+    client = Atum::Core::Client.client_from_schema(SCHEMA, uri.to_s, options)
+    @client = Client.new(client)
+  end
+
+  def self.client
+    if @client.nil?
+      raise "Client not initialized, call <%= @module_name %>.connect(...)"
+    end
+    @client
+  end
+
+  # Get customized options.
+  def self.custom_options(options)
+    return self.default_options if options.nil?
+
+    return self.default_options.merge(options) unless options[:default_headers]
+
+    opts = self.default_options.merge(options)
+    opts[:default_headers] = self.default_options[:default_headers].merge(options[:default_headers])
+
+    opts
+  end
+
+  # Get the default options.
+  def self.default_options
+    {
+      default_headers: {
+        <%= @default_headers.merge(
+            'User-Agent' => '#{user_agent}',
+            'Content-Type' => 'application/json'
+          ).map do |k, v|
+          "\"#{k.to_s}\" => \"#{v.to_s}\""
+        end.join(",\n        ") %>
+    } }
+  end
+
+  def self.user_agent
+    @user_agent ||=
+      begin
+        gem_name = "<%= @module_name.downcase.underscore.gsub("/", "-") %>"
+        gem_info = "#{gem_name}"
+        gem_info += "/v#{<%= @module_name %>::VERSION}" if defined?(<%= @module_name %>::VERSION)
+        ruby_engine = defined?(RUBY_ENGINE) ? RUBY_ENGINE : 'ruby'
+        ruby_version = RUBY_VERSION
+        ruby_version += " p#{RUBY_PATCHLEVEL}" if defined?(RUBY_PATCHLEVEL)
+        comment = ["#{ruby_engine} #{ruby_version}"]
+        comment << "atum v#{Atum::VERSION}"
+        comment << "faraday v#{Faraday::VERSION}"
+        comment << RUBY_PLATFORM if defined?(RUBY_PLATFORM)
+        "#{gem_info} (#{comment.join("; ")})"
+      end
+  end
+
+  SCHEMA = Atum::Core::Schema::ApiSchema.new(JSON.load(<<-'JSON'))
+<%= @schema %>
+JSON
+end

data/lib/atum/generation/generators/views/resource.erb

@@ -0,0 +1,33 @@
+# encoding: utf-8
+#
+# WARNING: Do not edit by hand, this file was generated by Atum:
+#
+#   https://github.com/gocardless/atum
+#
+require 'atum'
+require 'uri'
+
+module <%= @module_name %>
+<%= commentify(@description, 1) %>
+  class <%= @class_name %>
+    def initialize(client)
+      @client = client
+    end
+<% @links.each do |link| %>
+
+<%= commentify(link.description, 2) %>
+<%=
+  unless link.parameters.empty?
+    param_comments = link.parameters.map do |parameter|
+      "@param #{parameter.name}: #{parameter.description}"
+    end.join("\n")
+
+    commentify("\n" + param_comments, 2)
+  end
+%>
+    def <%= method(link.name, link.parameter_names_with_defaults) %>
+      @client.<%= @resource_name %>.<%= method(link.name, link.parameter_names) %>
+    end
+<% end %>
+  end
+end

data/lib/atum/generation/options_parameter.rb

@@ -0,0 +1,12 @@
+module Atum
+  module Generation
+    class OptionsParameter < Atum::Core::Schema::Parameter
+      attr_reader :default
+
+      def initialize
+        super(nil, 'options', 'any query parameters in the form of a hash')
+        @default = '{}'
+      end
+    end
+  end
+end

data/lib/atum/version.rb

@@ -0,0 +1,3 @@
+module Atum
+  VERSION = '0.5.0'
+end

data/spec/atum/core/client_spec.rb

@@ -0,0 +1,26 @@
+require 'spec_helper'
+
+describe Atum::Core::Client do
+  let(:client) { described_class.new({}, 'http://foo:bar@example.com') }
+
+  describe '#inspect' do
+    it 'should redact user password credentials' do
+      expect(client.inspect).to include('url="http://foo:REDACTED@example.com"')
+    end
+  end
+
+  describe '#unknown_resource' do
+    let(:client) { described_class.new({}, 'http://example.com') }
+    subject(:command) { -> { client.unknown_resource } }
+
+    context 'without a matching resource' do
+      it { is_expected.to raise_error(NoMethodError) }
+    end
+  end
+
+  describe '.client_from_schema' do
+    let(:schema) { Atum::Core::Schema::ApiSchema.new(SAMPLE_SCHEMA) }
+    subject { described_class.client_from_schema(schema, 'https://example.com') }
+    it { is_expected.to be_an(described_class) }
+  end
+end

data/spec/atum/core/errors_spec.rb

@@ -0,0 +1,19 @@
+require 'spec_helper'
+
+describe Atum::Core::ApiError do
+  let(:message) { 'Foo failed' }
+  let(:url) { 'http://example.com/how-to-fix' }
+
+  subject { described_class.new(error).message }
+
+  context 'without a documentation url' do
+    let(:error) { { 'message' => message } }
+    it { is_expected.to eq(message) }
+  end
+
+  context 'with a documentation url' do
+    let(:error) { { 'message' => message, 'documentation_url' => url } }
+    it { is_expected.to include(message) }
+    it { is_expected.to include(url) }
+  end
+end

data/spec/atum/core/link_spec.rb

@@ -0,0 +1,80 @@
+require 'spec_helper'
+
+describe Atum::Core::Link do
+  describe '.new' do
+    let(:url) { 'http://example.com' }
+    let(:link_schema) { double }
+    let(:options) { {} }
+    subject(:method) { -> { described_class.new(url, link_schema, options) } }
+
+    shared_examples_for 'creating a Faraday instance' do
+      it 'generates a new Faraday connection with the root url' do
+        expect(Faraday).to receive(:new).with(url: 'http://example.com')
+        method.call
+      end
+    end
+  end
+
+  describe '#run' do
+    let(:url) { 'http://example.com' }
+    let(:link_schema) { double(method: :get) }
+    let(:options) { {} }
+    let(:param_one) { double }
+    let(:envelope_name) { double }
+    let(:params) { [param_one, options] }
+    let(:fake_request) { double }
+    let(:fake_api_request) { double(request: fake_request) }
+    let(:link) { described_class.new(url, link_schema, options) }
+
+    before do
+      allow(link_schema).to receive_message_chain(
+        :resource_schema, :name, :pluralize).and_return(envelope_name)
+      allow(Atum::Core::Request).to receive(:new).and_return(fake_api_request)
+      allow(link_schema).to receive(:construct_path).and_return('/things')
+    end
+
+    context 'options' do
+      let(:headers) { { foo: 'bar' } }
+      let(:options) { { headers: headers } }
+
+      before do
+        allow(link).to receive(:default_options)
+          .and_return(headers: { bish: 'bash' })
+      end
+
+      it 'deep merges the options' do
+        expect(Atum::Core::Request).to receive(:new)
+          .with(anything, anything, anything,
+                hash_including(headers: { bish: 'bash', foo: 'bar' }))
+        link.run(param_one, options)
+      end
+
+      context 'when user headers would clash with the defaults' do
+        let(:headers) { { bish: 'bosh' } }
+        it 'overrides the default headers with user headers' do
+          expect(Atum::Core::Request).to receive(:new)
+            .with(anything, anything, anything,
+                  hash_including(headers: { bish: 'bosh' }))
+          link.run(param_one, options)
+        end
+      end
+    end
+
+    context 'the passed http method' do
+      let(:http_method) { double }
+      before { allow(link_schema).to receive(:method).and_return(http_method) }
+      it 'should be from the link schema' do
+        expect(Atum::Core::Request).to receive(:new)
+          .with(anything, http_method, anything, anything)
+        link.run(param_one, options)
+      end
+    end
+
+    context 'when the last parameter is not an options hash' do
+      subject { -> { link.run(*params) } }
+      let(:params) { [] }
+      it { is_expected.to raise_error(ArgumentError) }
+    end
+
+  end
+end

data/spec/atum/core/paginator_spec.rb

@@ -0,0 +1,72 @@
+require 'spec_helper'
+
+describe Atum::Core::Paginator do
+  let(:items) do
+    (1..100).map do |i|
+      { name: "item_#{i}" }
+    end
+  end
+  let(:initial_limit) { 50 }
+  let(:limit_increment) { 50 }
+  let(:request) { double(make_request: response) }
+  let(:response) { double(body: anything) }
+  let(:options) { {} }
+  let(:paginator) { described_class.new(request, response, options) }
+  let(:after) { double }
+
+  describe '#enumerator' do
+    subject(:enumerator) { paginator.enumerator }
+    before do
+      allow(request).to receive(:unenvelope)
+        .and_return(items[0...initial_limit],
+                    items[initial_limit...initial_limit * 2])
+      allow(response).to receive(:limit)
+        .and_return(initial_limit, initial_limit,
+                    initial_limit + limit_increment,
+                    initial_limit + limit_increment)
+      allow(response).to receive(:meta)
+        .and_return('cursors' => { 'after' => after })
+    end
+
+    it { is_expected.to be_an(Enumerator) }
+
+    context 'when the number of items required is < LIMIT_INCREMENT' do
+      before { stub_const('Atum::Core::Paginator::LIMIT_INCREMENT', limit_increment) }
+
+      it "doesn't fetch any more pages of data" do
+        expect(request).to_not receive(:make_request)
+        enumerator.take(limit_increment - 1).to_a
+      end
+    end
+
+    context 'when the number of items required is = LIMIT_INCREMENT' do
+      before { stub_const('Atum::Core::Paginator::LIMIT_INCREMENT', limit_increment) }
+
+      it "doesn't fetch any more pages of data" do
+        expect(request).to_not receive(:make_request)
+        enumerator.take(limit_increment).to_a
+      end
+    end
+
+    context 'when the number of items required is > LIMIT_INCREMENT' do
+      before { stub_const('Atum::Core::Paginator::LIMIT_INCREMENT', limit_increment) }
+
+      it 'fetches another page of data' do
+        expect(request).to receive(:make_request).once
+        enumerator.take(limit_increment + 1).to_a
+      end
+
+      it 'sends after as a query param' do
+        expect(request).to receive(:make_request)
+          .with(query: hash_including(after: after))
+        enumerator.take(limit_increment + 1).to_a
+      end
+
+      it 'increases the requested limit on each successive fetch' do
+        expect(request).to receive(:make_request)
+          .with(query: hash_including(limit: initial_limit + limit_increment))
+        enumerator.take(limit_increment + 1).to_a
+      end
+    end
+  end
+end

data/spec/atum/core/request_spec.rb

@@ -0,0 +1,110 @@
+require 'spec_helper'
+
+describe Atum::Core::Request do
+  let(:root_url) { 'http://example.com' }
+  let(:path) { '/things' }
+  let(:querystring) { '' }
+  let(:full_path) { "#{root_url}#{path}#{querystring}" }
+  let(:method) { :get }
+  let(:connection) { Faraday.new(url: root_url) }
+  let(:pre_processor) { nil }
+  let(:headers) { {} }
+  let(:body) { nil }
+  let(:query) { {} }
+  let(:options) do
+    {
+      headers: headers,
+      body: body,
+      query: query,
+      envelope_name: 'things'
+    }
+  end
+  subject(:requestor) { described_class.new(connection, method, path, options) }
+
+  describe '#request' do
+    let(:make_request) { -> { requestor.request } }
+    before { stub }
+
+    context 'passing headers' do
+      let(:headers) { { 'Foo' => 'BarBaz' } }
+      let(:stub) { stub_request(:get, full_path).with(headers: headers) }
+
+      it 'works as expected' do
+        make_request.call
+        expect(stub).to have_been_requested
+      end
+    end
+
+    context 'passing a body' do
+      let(:method) { :post }
+      let(:body) { { 'Foo' => 'BarBaz' } }
+      let(:stub) { stub_request(:post, full_path).with(body: body) }
+
+      it 'works as expected' do
+        make_request.call
+        expect(stub).to have_been_requested
+      end
+    end
+
+    context 'passing a query' do
+      let(:query) { { 'a' => 'b' } }
+      let(:stub) { stub_request(:get, full_path).with(query: query) }
+
+      it 'works as expected' do
+        make_request.call
+        expect(stub).to have_been_requested
+      end
+    end
+
+    context 'when the response is not JSON' do
+      let(:response) { 'ABCDEFGH' }
+      let(:stub) do
+        stub_request(:get, full_path)
+          .with(query: query)
+          .to_return(body: response,
+                     headers: { 'Content-Type' => 'application/text' })
+      end
+
+      it 'returns the raw response' do
+        expect(make_request.call).to eq(response)
+      end
+    end
+
+    context 'when the response is json' do
+      context 'and is not paginated' do
+        let(:response_body) { { 'ABC' => 'DEF' } }
+        let(:response) { { 'things' => response_body } }
+        let(:stub) do
+          stub_request(:get, full_path)
+            .with(query: query)
+            .to_return(body: response.to_json,
+                       headers: { 'Content-Type' => 'application/json' })
+        end
+
+        it 'returns an unenveloped body' do
+          expect(requestor).to receive(:unenvelope).with(response)
+            .and_return(response_body)
+          make_request.call
+        end
+      end
+
+      context 'and is paginated' do
+        let(:limit) { 50 }
+        let(:response) { { 'things' => (0..limit).map { |i| "item_#{i}" } } }
+        let(:stub) do
+          stub_request(:get, full_path)
+            .to_return(body: {
+              resources: response,
+              meta: {
+                limit: limit, cursors: { before: 'beforeID', after: 'afterID' }
+              }
+            }.to_json, headers: { 'Content-Type' => 'application/json' })
+        end
+
+        it 'returns an Enumerator' do
+          expect(make_request.call).to be_an(Enumerator)
+        end
+      end
+    end
+  end
+end