moneybird-client 0.12.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at maartenvanvliet@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in the gemspec
+gemspec
+
+group :coverage do
+  gem "simplecov", "~> 0.22"
+  gem "simplecov-cobertura", "~> 2.1"
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Maarten van Vliet
+
+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/README.md

@@ -0,0 +1,110 @@
+# Moneybird [![CI](https://codeberg.org/odeva/moneybird/actions/workflows/ruby.yml/badge.svg)](https://codeberg.org/odeva/moneybird/actions/workflows/ruby.yml)
+
+Ruby client for the [Moneybird REST API](https://developer.moneybird.com/). Supports both personal API tokens and OAuth2 authentication.
+
+> [!IMPORTANT]
+> This is a fork of [maartenvanvliet/moneybird](https://github.com/maartenvanvliet/moneybird), this is a very solid implementation that I really wanted to build on top of.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'moneybird-client', require: 'moneybird'
+```
+
+And then execute:
+
+    $ bundle
+
+## Usage
+
+```ruby
+client = Moneybird::Client.new('your_bearer_token')
+
+# List administrations
+administrations = client.administrations
+
+administration = administrations.first
+
+# List invoices
+administration.sales_invoices.all
+
+# List invoices with a specific state
+administration.sales_invoices.all(filter: 'state:uncollectible')
+
+# List contacts
+administration.contacts.all
+
+# Find contact
+administration.contacts.find(moneybird_id)
+
+# Find contact by customer id
+administration.contacts.find_by_customer_id(customer_id)
+
+# Create contact
+administration.contacts.create(company_name: 'ACME', firstname: 'Foo', lastname: 'Bar')
+
+# Update contact
+contact = administration.contacts.all.first
+contact.company_name = 'Something new'
+administrations.contacts.save(contact)
+
+# Delete contact
+administrations.contacts.delete(contact)
+
+# Works similarly with other resources
+
+```
+### OAuth2
+
+Moneybird uses OAuth2 for authentication. Use `Moneybird::OAuth` to handle the flow:
+
+```ruby
+oauth = Moneybird::OAuth.new(
+  client_id: "your_client_id",
+  client_secret: "your_client_secret",
+  redirect_uri: "https://yourapp.com/callback"
+)
+
+# Step 1: Redirect user
+redirect_to oauth.authorize_url(scope: %w[sales_invoices documents])
+
+# Step 2: Exchange code (in callback)
+token = oauth.token(params[:code])
+
+# Step 3: Use the token
+client = token.client
+administrations = client.administrations
+
+# Step 4: Refresh when needed
+new_token = oauth.refresh(token.refresh_token)
+```
+
+Available scopes: `sales_invoices`, `documents`, `estimates`, `bank`, `time_entries`, `settings`.
+
+The `authorize_url` method accepts an optional `state` parameter for CSRF protection.
+
+### Webhooks
+
+Moneybird, if so configured, sends webhooks to specified endpoints. This gem can deal with these requests.
+```ruby
+webhook = Moneybird::Webhook.from_json(request.body)
+sales_invoice = webhook.build_entity
+sales_invoice.state
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` 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).
+
+## Contributing
+
+Bug reports and pull requests are welcome on Codeberg at https://codeberg.org/odeva/moneybird. 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](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |t|
+  t.libs.push 'spec'
+  t.test_files = FileList['spec/**/*_spec.rb']
+end
+
+task default: :test

data/bin/console

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "moneybird"
+require "irb"
+
+if ENV['MONEYBIRD_API_TOKEN']
+  @client = Moneybird::Client.new(ENV['MONEYBIRD_API_TOKEN'])
+end
+
+IRB.start
+
+

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/lib/moneybird/client.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module Moneybird
+  class Client
+    attr_reader :bearer_token
+    attr_accessor :errors
+    attr_writer :http, :faraday_adapter
+
+    def initialize(bearer_token)
+      @bearer_token = bearer_token
+    end
+
+    def base_url
+      "https://moneybird.com/"
+    end
+
+    def version
+      @version ||= 'v2'
+    end
+
+    def faraday_adapter
+      @faraday_adapter ||= Faraday.default_adapter
+    end
+
+    def http
+      @http ||= Faraday.new(url: base_url) do |faraday|
+        faraday.headers = faraday_headers
+        faraday.request :url_encoded
+        faraday.response :json
+        faraday.use Moneybird::Middleware::ErrorHandling
+        faraday.use Moneybird::Middleware::Pagination
+
+        faraday.adapter faraday_adapter
+      end
+    end
+
+    %i[get patch post delete].each do |call|
+      define_method call do |path, options = {}|
+        response = http.public_send(call, "/api/#{version}/#{path}", options)
+        if response.status == 302
+          response['Location']
+        else
+          response.body
+        end
+      end
+    end
+
+    def get_all_pages(path, options = {})
+      get_each_page(path, options).inject([]) do |array, objects|
+        array += objects
+      end
+    end
+
+    def get_each_page(path, options = {})
+      return enum_for(:get_each_page, path, options) unless block_given?
+      path = "/api/#{version}/#{path}"
+      while path
+        response = http.get(path, options)
+        yield response.body
+        path = (response[:pagination_links].next if response[:pagination_links])
+      end
+    end
+
+    def administrations
+      Moneybird::Service::Administration.new(self).all
+    end
+
+    private
+
+    def faraday_headers
+      {
+        'Accept' => 'application/json',
+        'Content-Type' => 'application/json',
+        'Authorization' => "Bearer #{bearer_token}"
+      }
+    end
+  end
+end

data/lib/moneybird/http_error/authorization_required.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class AuthorizationRequired < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/http_error/bad_request.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class BadRequest < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/http_error/forbidden.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class Forbidden < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/http_error/internal_server_error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class InternalServerError < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/http_error/method_not_allowed.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class MethodNotAllowed < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/http_error/not_accepted.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class NotAccepted < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/http_error/not_found.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class NotFound < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/http_error/payment_required.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class PaymentRequired < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/http_error/too_many_requests.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class TooManyRequests < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/http_error/unprocessable_entity.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module HttpError
+    class UnprocessableEntity < Faraday::Error
+    end
+  end
+end

data/lib/moneybird/middleware/error_handling.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Moneybird
+  module Middleware
+    class ErrorHandling < Faraday::Middleware
+      ERROR_MAP = {
+        400 => Moneybird::HttpError::BadRequest,
+        401 => Moneybird::HttpError::AuthorizationRequired,
+        402 => Moneybird::HttpError::PaymentRequired,
+        403 => Moneybird::HttpError::Forbidden,
+        404 => Moneybird::HttpError::NotFound,
+        405 => Moneybird::HttpError::MethodNotAllowed,
+        406 => Moneybird::HttpError::NotAccepted,
+        422 => Moneybird::HttpError::UnprocessableEntity,
+        429 => Moneybird::HttpError::TooManyRequests,
+        500 => Moneybird::HttpError::InternalServerError
+      }.freeze
+
+      def on_complete(response)
+        key = response[:status].to_i
+        raise ERROR_MAP[key], response_values(response) if ERROR_MAP.key? key
+      end
+
+      def response_values(response)
+        { status: response.status, headers: response.response_headers, body: response.body }
+      end
+    end
+  end
+end

data/lib/moneybird/middleware/pagination/links.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'link_header'
+
+module Moneybird
+  module Middleware
+    class Pagination < Faraday::Middleware
+      class Links
+        attr_accessor :first, :prev, :current, :next, :last
+        alias previous prev
+        alias prevous= prev=
+
+        def last_page?
+          !current.nil? && !last.nil? && current == last
+        end
+      end
+    end
+  end
+end

data/lib/moneybird/middleware/pagination.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'link_header'
+
+module Moneybird
+  module Middleware
+    class Pagination < Faraday::Middleware
+      def on_complete(response)
+        return unless response[:response_headers]
+        link_header = response[:response_headers][:link]
+        return unless link_header
+        response[:response_headers][:pagination_links] = find_links(link_header)
+      end
+
+      private
+
+      def find_links(link_header)
+        Links.new.tap do |links|
+          %w[prev next first last current].each do |page|
+            links.public_send("#{page}=", find_link(link_header, page))
+          end
+        end
+      end
+
+      def find_link(header, rel)
+        link = ::LinkHeader.parse(header).links.find { |l| l['rel'] == rel }
+        link.to_a.first if link
+      end
+    end
+  end
+end

data/lib/moneybird/oauth.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'faraday'
+
+module Moneybird
+  class OAuth
+    AUTHORIZE_URL = "https://moneybird.com/oauth/authorize"
+    TOKEN_URL = "https://moneybird.com/oauth/token"
+
+    SCOPES = %w[sales_invoices documents estimates bank time_entries settings].freeze
+
+    attr_reader :client_id, :client_secret, :redirect_uri
+
+    def initialize(client_id:, client_secret:, redirect_uri:)
+      @client_id = client_id
+      @client_secret = client_secret
+      @redirect_uri = redirect_uri
+    end
+
+    # Returns the URL to redirect the user to for authorization
+    def authorize_url(scope: nil, state: nil)
+      scope = scope.is_a?(Array) ? scope.join(" ") : (scope || "sales_invoices")
+
+      params = {
+        client_id: client_id,
+        redirect_uri: redirect_uri,
+        response_type: "code",
+        scope: scope
+      }
+      params[:state] = state if state
+
+      uri = URI.parse(AUTHORIZE_URL)
+      uri.query = URI.encode_www_form(params)
+      uri.to_s
+    end
+
+    # Exchange authorization code for tokens
+    # Returns a Token object
+    def token(code)
+      response = post_token(
+        grant_type: "authorization_code",
+        client_id: client_id,
+        client_secret: client_secret,
+        code: code,
+        redirect_uri: redirect_uri
+      )
+      build_token(response)
+    end
+
+    # Refresh an existing token
+    # Returns a new Token object
+    def refresh(refresh_token)
+      response = post_token(
+        grant_type: "refresh_token",
+        client_id: client_id,
+        client_secret: client_secret,
+        refresh_token: refresh_token
+      )
+      build_token(response)
+    end
+
+    private
+
+    def post_token(params)
+      connection = Faraday.new do |faraday|
+        faraday.request :url_encoded
+        faraday.response :json
+        faraday.adapter Faraday.default_adapter
+      end
+
+      response = connection.post(TOKEN_URL, params)
+
+      unless response.success?
+        raise "OAuth token request failed with status #{response.status}: #{response.body}"
+      end
+
+      response.body
+    end
+
+    def build_token(body)
+      Token.new(
+        access_token: body["access_token"],
+        refresh_token: body["refresh_token"],
+        token_type: body.fetch("token_type", "bearer"),
+        scope: body["scope"],
+        created_at: body["created_at"]
+      )
+    end
+  end
+end

data/lib/moneybird/resource/administration.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Moneybird::Resource
+  class Administration
+    include Moneybird::Resource
+    extend Moneybird::Resource::ClassMethods
+
+    has_attributes %i(
+      id
+      name
+      language
+      currency
+      country
+      time_zone
+    )
+
+    def ledger_accounts
+      Moneybird::Service::LedgerAccount.new(@client, id)
+    end
+
+    def purchase_invoices
+      Moneybird::Service::PurchaseInvoice.new(@client, id)
+    end
+
+    def sales_invoices
+      Moneybird::Service::SalesInvoice.new(@client, id)
+    end
+
+    def external_sales_invoices
+      Moneybird::Service::ExternalSalesInvoice.new(@client, id)
+    end
+
+    def recurring_sales_invoices
+      Moneybird::Service::RecurringSalesInvoice.new(@client, id)
+    end
+
+    def contacts
+      Moneybird::Service::Contact.new(@client, id)
+    end
+
+    def estimates
+      Moneybird::Service::Estimate.new(@client, id)
+    end
+
+    def products
+      Moneybird::Service::Product.new(@client, id)
+    end
+
+    def webhooks
+      Moneybird::Service::Webhook.new(@client, id)
+    end
+
+    def identities
+      Moneybird::Service::Identity.new(@client, id)
+    end
+
+    def workflows
+      Moneybird::Service::Workflow.new(@client, id)
+    end
+
+    def custom_fields
+      Moneybird::Service::CustomField.new(@client, id)
+    end
+
+    def document_styles
+      Moneybird::Service::DocumentStyle.new(@client, id)
+    end
+
+    def tax_rates
+      Moneybird::Service::TaxRate.new(@client, id)
+    end
+
+    def financial_accounts
+      Moneybird::Service::FinancialAccount.new(@client, id)
+    end
+
+    def financial_mutations
+      Moneybird::Service::FinancialMutation.new(@client, id)
+    end
+
+    def general_documents
+      Moneybird::Service::Document::GeneralDocument.new(@client, id)
+    end
+
+    def general_journal_documents
+      Moneybird::Service::Document::GeneralJournalDocument.new(@client, id)
+    end
+
+    def receipts
+      Moneybird::Service::Document::Receipt.new(@client, id)
+    end
+
+    def purchase_invoice_documents
+      Moneybird::Service::Document::PurchaseInvoice.new(@client, id)
+    end
+
+    def typeless_documents
+      Moneybird::Service::Document::TypelessDocument.new(@client, id)
+    end
+  end
+end