badbill 0.0.1

data/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# How to contribute
+
+This API client is implemented for my own use, so I will only work on the parts I need for myself.
+Additional improvements, comments on code and implementation and bug fixes are very welcome.
+
+## Report bugs, improvements or feature requests
+
+* Submit a ticket for your issue, assuming one does not already exist.
+  * Clearly describe the issue including steps to reproduce when it is a bug.
+  * Make sure you fill in the earliest version that you know has the issue.
+
+## Making Changes
+
+* Fork the repository on GitHub.
+* Create a topic branch from where you want to base your work.
+* Make commits of logical units.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format.
+* Run _all_ the tests to assure nothing else was accidentally broken.
+* Include tests for new features and bug fixes (if you don't know how to do that, feel free to ask, I will help).
+
+
+## Submitting Changes
+
+* Push your changes to a topic branch in your fork of the repository.
+* Submit a pull request to the repository.
+* Wait for my response.
+
+# Contact
+
+Feel free to contact me with any issues or questions.
+
+* Mail: badboy@archlinux.us
+* Twitter: [@badboy_](https://twitter.com/badboy_)

data/Gemfile

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+group :development do
+  gem 'yard'
+  gem 'redcarpet'
+  gem 'simplecov'
+end
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,51 @@
+PATH
+  remote: .
+  specs:
+    badbill (0.0.1)
+      faraday
+      faraday_middleware
+      hashie
+      yajl-ruby
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.3.2)
+    crack (0.3.1)
+    diff-lcs (1.1.3)
+    faraday (0.8.4)
+      multipart-post (~> 1.1)
+    faraday_middleware (0.8.8)
+      faraday (>= 0.7.4, < 0.9)
+    hashie (1.2.0)
+    multi_json (1.3.6)
+    multipart-post (1.1.5)
+    redcarpet (2.1.1)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.3)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.3)
+    simplecov (0.6.4)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+    webmock (1.8.10)
+      addressable (>= 2.2.7)
+      crack (>= 0.1.7)
+    yajl-ruby (1.1.0)
+    yard (0.8.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  badbill!
+  redcarpet
+  rspec
+  simplecov
+  webmock
+  yard

data/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) 2012 Jan-Erik Rediger <http://fnordig.de/about/>
+
+Permission  is  hereby granted, free of charge, to any person ob-
+taining a copy of  this  software  and  associated  documentation
+files  (the "Software"), to deal in the Software without restric-
+tion, including without limitation the rights to use, copy, modi-
+fy, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is  fur-
+nished 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  NONIN-
+FRINGEMENT. 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/README.md

@@ -0,0 +1,92 @@
+BadBill - Billomat API Client
+===================
+
+Simple but working API client for the [Billomat API][apidocu].
+
+See the [API documentation][apidocu] for full documentation of all resources.
+
+## Features
+
+* Fast and easy access to all resources the API provides
+  (not all resources are Ruby classes, yet)
+* Full documentation.
+* Test coverage as best as I can.
+* Production-ready (it's for a job project).
+
+## What's working right now
+
+The basic BadBill class allows access to all resources. It includes no syntactic sugar to work with, instead it just returns the data as a hash. This works for basic usage.
+
+The following resources are currently implemented as its own class:
+
+* [clients](http://www.billomat.com/en/api/invoices/) (`BadBill::Client`)
+* [invoices](http://www.billomat.com/en/api/invoices/) (`BadBill::Invoices`)
+
+These are the two I need right now.
+Implementing new resources is easy. Pull Requests for others are welcome.
+
+## Requirements
+
+* [yajl-ruby](https://github.com/brianmario/yajl-ruby)
+* [faraday](https://github.com/technoweenie/faraday)
+* [faraday_middleware](https://github.com/pengwynn/faraday_middleware)
+* [hashie](https://github.com/intridea/hashie)
+
+## Installation
+
+BadBill is just a `gem install badbill` away. Get an API key for the Billomat API on your profile page.
+
+## Examples
+
+### Basic Usage
+
+    bill = BadBill.new "billo", "18e40e14"
+    # => #<BadBill:0x00000001319d30 ...>
+    bill.get 'settings'
+    # => {"settings"=>
+    #   {"invoice_intro"=>"",
+    #    "invoice_note"=>"",
+    #    ...}}
+    bill.put 'settings', settings: { invoice_intro: "Intro" }
+    # => {"settings"=>
+    #   {"invoice_intro"=>"Intro",
+    #    "invoice_note"=>"",
+    #    ...}}
+
+### Using defined resource classes
+
+    BadBill.new "billo", "18e40e14"
+
+    BadBill::Invoice.all
+    # => [#<BadBill::Invoice:0x000000024caf98 @id="1" @data={...}>], ...]
+
+    invoice = BadBill::Invoice.find(1)
+    invoice.pdf
+    # => {"id"=>"1",
+    #     "created"=>"2012-09-17T13:58:42+02:00",
+    #     "invoice_id"=>"322791",
+    #     "filename"=>"Invoice 322791.pdf",
+    #     "mimetype"=>"application/pdf",
+    #     "filesize"=>"90811",
+    #     "base64file"=>"JVBERi0xLjM..."}
+    invoice.delete
+    # => true
+
+    BadBill::Invoice.create client_id: 1, date: "2012-09-18", note: "Thank you for your order", ...
+
+## Documentation
+
+Documentation is online at [rubydoc.info](http://rubydoc.info/github/badboy/badbill/master/frames).
+
+Generate locale documentation with `rake doc` ([yard](http://yardoc.org/) required).
+Required Parameters and possible values won't be documentated here. See the [API documentation][apidocu] for that.
+
+## Contribute
+
+See [CONTRIBUTING.md](/badboy/badbill/blob/master/CONTRIBUTING.md) for info.
+
+## License
+
+See [LICENSE](/badboy/badbill/blob/master/LICENSE) for info.
+
+[apidocu]: http://www.billomat.com/en/api/

data/Rakefile

@@ -0,0 +1,85 @@
+require 'date'
+require 'fileutils'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+
+require 'yard'
+YARD::Rake::YardocTask.new do |t|
+  t.files   = ['lib/**/*.rb']
+end
+
+task :default => :spec
+task :doc => :yard
+
+## helper functions
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
+
+def gem_file
+  "#{name}-#{version}.gem"
+end
+
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
+end
+
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+## release management tasks
+
+desc "Commit, create tag v#{version} and build and push #{gem_file} to Rubygems"
+task :release => :build do
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{gem_file}"
+end
+
+desc "Build #{gem_file} into the pkg directory"
+task :build => :gemspec do
+  FileUtils.mkdir_p 'pkg'
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+desc "Generate #{gemspec_file}"
+task :gemspec do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(doc|coverage|pkg)/ }.
+    map { |file| "    ./#{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end

data/lib/badbill/base_resource.rb

@@ -0,0 +1,118 @@
+# encoding: utf-8
+
+class BadBill
+  class BaseResource
+    include BadBill::Resource
+    extend BadBill::Resource
+
+    include BadBill::ForwardMethods
+
+    # ID of the resource.
+    attr_reader   :id
+    # All data in a Hash.
+    attr_accessor :data
+
+    # Public: Create new resource object.
+    #
+    # @param [String,Integer] id The ID of the resource.
+    # @param [Hashie::Mash] data Resource data.
+    #
+    # All resources have an ID and data. Methods are proxied to the data object.
+    #
+    # @return [Resource] A new resource.
+    def initialize id, data
+      @id   = id
+      @data = data
+    end
+
+    # Get all resources of this type.
+    #
+    # @param [Hash] filter An Hash of filter parameters,
+    #                      see the online documentation for allowed values.
+    #
+    # @return [Array<Resource>] All found resources.
+    def self.all filter={}
+      all = get resource_name, filter
+      all.__send__(resource_name).__send__(resource_name_singular).map do |res|
+        new res.id, res
+      end
+    end
+
+    # Get the resource with the given ID.
+    #
+    # @param [String,Integer] id ID of the resource.
+    #
+    # @return [Resource] New resource with id and data set.
+    def self.find id
+      c = get resource_name, id
+      new id, c.__send__(resource_name_singular)
+    end
+
+    # Create a new resource with the given parameters.
+    #
+    # @param [Hash] params A Hash-like object of data.
+    #                      See the online documentation for allowed values.
+    #
+    # @return [Resource] New resource with id and data set.
+    def self.create params
+      res = post(resource_name, {resource_name_singular => params})
+      res_data = res.__send__(resource_name_singular)
+      new res_data.id, res_data
+    end
+
+    # Save any changed data.
+    #
+    # @return [Boolean] True if successfull, false otherwise.
+    def save
+      @data.id = id
+      resp = put resource_name, id, {resource_name_singular => @data}
+      !resp
+    end
+
+    # Delete this resource.
+    #
+    # @return [Boolean] True if successfull, false otherwise.
+    def delete
+      # Hack: We can't call #delete here, because we ARE #delete
+      resp = call resource_name, id, nil, :delete
+      !resp
+    end
+
+    # Protect overriding of the ID.
+    #
+    # @raise [NoMethodError] because the ID may not be overwritten.
+    def id= *args
+      raise NoMethodError, "undefined method `id=' for '#{self.inspect.sub(/ .+/, '>')}`"
+    end
+
+    private
+
+    def resource_name_singular
+      self.class.resource_name_singular
+    end
+
+    def resource_name
+      self.class.resource_name
+    end
+
+    # The singular resource name for use with the API.
+    #
+    # By default this is just the Class name, but it may be overridden.
+    # Make sure to overwrite resource_name, too.
+    #
+    # @return [String] The singular resource name.
+    def self.resource_name_singular
+      @resource_name_singular ||= self.name.split(/::/).last.downcase
+    end
+
+    # The resource name (plural) for use with the API.
+    #
+    # By default this is just the `resource_name_singular` with an appended 's'
+    # See #resource_name_singular
+    #
+    # @return [String] The resource name.
+    def self.resource_name
+      @resource_name ||= "#{resource_name_singular}s"
+    end
+  end
+end

data/lib/badbill/client.rb

@@ -0,0 +1,32 @@
+# encoding: utf-8
+
+class BadBill
+  # The clients resource handles all clients.
+  #
+  # See http://www.billomat.com/en/api/clients/
+  class Client < BaseResource
+    attr_writer :myself
+
+    def initialize id, data
+      super
+      @myself = false
+    end
+
+    # Fetch information about yourself.
+    #
+    # @return [Client] A new resource.
+    def self.myself
+      c = get 'clients', 'myself'
+      client = new c.client.id, c.client
+      client.myself = true
+      client
+    end
+
+    # Indicates wether this resource is yourself or not.
+    #
+    # @return [Boolean] Wether or not this resource is yourself.
+    def myself?
+      @myself
+    end
+  end
+end

data/lib/badbill/forward_methods.rb

@@ -0,0 +1,30 @@
+# encoding: utf-8
+
+class BadBill
+  # Forward all methods to an underlying object called data.
+  #
+  # This acts like a proxy object.
+  module ForwardMethods
+    # Respond to method_missing to send down the line.
+    #
+    # As Hashie::Mash#method_missing does not respond with true to an
+    # assignment request, we only check for the method name without the equal sign.
+    def method_missing(method_name, *arguments, &block)
+      if data.respond_to?(method_name.to_s.sub(/=$/, ''))
+        data.send(method_name, *arguments, &block)
+      else
+        super
+      end
+    end
+
+    # Proxy respond_to? to the underlying object if needed.
+    #
+    # If playing with method_missing define respond_to? too.
+    # See http://robots.thoughtbot.com/post/28335346416/always-define-respond-to-missing-when-overriding
+    #
+    # @return [Boolean] True if the class itself or the proxied object responds to the given method.
+    def respond_to?(method_name, include_private = false)
+      super || data.respond_to?(method_name, include_private)
+    end
+  end
+end

data/lib/badbill/invoice.rb

@@ -0,0 +1,106 @@
+# encoding: utf-8
+
+require 'base64'
+
+class BadBill
+  # The resource handles all invoices.
+  #
+  # See http://www.billomat.com/en/api/invoices
+  class Invoice < BaseResource
+    # Get the PDF invoice.
+    #
+    #
+    # @return [Hashie::Mash] Hash containing the ID, filesize, base64file and
+    #                        other parameters.
+    #                        See http://www.billomat.com/en/api/invoices for
+    #                        all parameters.
+    def pdf
+      resp = get resource_name, "#{id}/pdf"
+      resp.pdf
+    end
+
+    # Closes a statement in the draft status (DRAFT). Here, the
+    # status of open (OPEN) or overdue (OVERDUE) is set and a PDF is
+    # generated and stored in the file system.
+    #
+    # @param [String,Integer] template_id ID of the Template used to create pdf,
+    #                                     If not set, default template is used.
+    #
+    # @return [Boolean] Wether or not the call was successfull.
+    def complete template_id=nil
+      data = { complete: {} }
+      data[:complete] = { template_id: template_id } if template_id
+      resp = put resource_name, "#{id}/complete", data
+
+      !resp
+    end
+
+    # Cancel an invoice.
+    #
+    # @return [Boolean] Wether or not the call was successfull.
+    def cancel
+      resp = put resource_name, "#{id}/cancel"
+      !resp
+    end
+
+    # Sends an invoice by email.
+    #
+    # @param [String] to      Recipient of the email.
+    #                         cc and bcc can be set in the `more` Hash.
+    # @param [String] from    Sender email address.
+    # @param [String] subject Subject for the email.
+    # @param [String] body    Body for the email.
+    # @param [Hash] more      Hash-like object including more options.
+    #                         See online documentation for all allowed parameters.
+    #
+    # from, subject or body can be replaced by more.
+    #
+    # @return [Boolean] Wether or not the call was successfull.
+    def email to, from=nil, subject=nil, body=nil, more={}
+      data = { recipients: {} }
+
+      if more.empty? && from.kind_of?(Hash)
+        more = from
+        from = nil
+      end
+
+      if more.empty? && subject.kind_of?(Hash)
+        more = subject
+        subject = nil
+      end
+
+      if more.empty? && body.kind_of?(Hash)
+        more = body
+        body = nil
+      end
+
+      data[:from]    = from    if from
+      data[:subject] = subject if subject
+      data[:body]    = body    if body
+
+      data.merge! more
+      data[:recipients][:to] = to
+
+      resp = post resource_name, "#{id}/email", email: data
+      !resp
+    end
+
+    # Uploads a digital signature for a given invoice.
+    #
+    # The status of the invoice may not be DRAFT.
+    #
+    # @param [String,#read] file file name or a object responding to #read.
+    #                            This will be base64-encoded before send.
+    #
+    # @return [Boolean] false if status is DRAFT or another error occured. true if everything was successfull.
+    def upload_signature file
+      return false if data.status == 'DRAFT'
+
+      file = File.open(file, 'r') unless file.respond_to?(:read)
+
+      base64 = Base64.encode64 file.read
+      put resource_name, "#{id}/upload-signature", { signature: { base64file: base64 } }
+      true
+    end
+  end
+end

data/lib/badbill/resource.rb

@@ -0,0 +1,34 @@
+# encoding: utf-8
+
+class BadBill
+  # Forward requests to the underlying connection object.
+  #
+  # This module is included in BadBill::BaseResource.
+  module Resource
+    # @param (see BadBill#get)
+    def get resource, id='', options=nil
+      call resource, id, options, :get
+    end
+
+    # @param (see BadBill#post)
+    def post resource, id='', options=nil
+      call resource, id, options, :post
+    end
+
+    # @param (see BadBill#put)
+    def put resource, id='', options=nil
+      call resource, id, options, :put
+    end
+
+    # @param (see BadBill#delete)
+    def delete resource, id='', options=nil
+      call resource, id, options, :delete
+    end
+
+    # @param (see BadBill#call)
+    def call resource, id='', options=nil, method=:get
+      raise BadBill::NoConnection, "No connection. Use BadBill.new first." if BadBill.connection.nil?
+      BadBill.connection.call resource, id, options, method
+    end
+  end
+end