moloni 0.5.0

data/README.md

@@ -0,0 +1,184 @@
+# Moloni
+
+A modern Ruby wrapper for the [Moloni API](https://www.moloni.pt/dev/). Works with Ruby 3.2+ and Rails 8.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'moloni'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install moloni
+
+## Setup
+
+### In a Rails app
+
+Create `config/initializers/moloni.rb`:
+
+```ruby
+Moloni.configure do |config|
+  config.developer_id = ENV.fetch('MOLONI_DEVELOPER_ID')
+  config.redirect_uri = ENV.fetch('MOLONI_REDIRECT_URI')
+  config.client_secret = ENV.fetch('MOLONI_CLIENT_SECRET')
+  config.access_token = ENV.fetch('MOLONI_ACCESS_TOKEN')
+  config.refresh_token = ENV.fetch('MOLONI_REFRESH_TOKEN')
+  config.company_id = ENV.fetch('MOLONI_COMPANY_ID', 0)
+end
+```
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `MOLONI_DEVELOPER_ID` | OAuth `client_id` from Moloni developer area |
+| `MOLONI_REDIRECT_URI` | OAuth callback URL |
+| `MOLONI_CLIENT_SECRET` | OAuth `client_secret` |
+| `MOLONI_ACCESS_TOKEN` | Short-lived API token (1h) |
+| `MOLONI_REFRESH_TOKEN` | Long-lived refresh token (14 days) |
+| `MOLONI_COMPANY_ID` | Default company for API calls |
+
+## Authentication
+
+The gem supports OAuth 2.0. Use the built-in CLI tool to obtain tokens:
+
+```bash
+bin/auth
+```
+
+This starts a local callback server and opens the browser for Moloni authorization. After approval, tokens are printed to the console.
+
+**Token auto-refresh:** The gem automatically refreshes expired `access_token`s using the `refresh_token` before each API call (with a 5-minute safety margin). If the refresh token also expires, a `Moloni::TokenExpiredError` is raised.
+
+## Usage
+
+### Basic API calls
+
+All API calls use `POST` under the hood, including reads. The gem automatically injects `company_id`, `access_token`, `json=true`, and `human_errors=true`.
+
+```ruby
+# List all products
+products = Moloni::Product.getAll
+
+# Find one product
+product = Moloni::Product.getOne(product_id: 123)
+
+# Search by EAN (or any future method)
+product = Moloni::Product.getByEAN(ean: '5601234567890')
+
+# Snake_case also works
+product = Moloni::Product.get_by_ean(ean: '5601234567890')
+```
+
+### Dynamic dispatch
+
+Any method name not explicitly defined on a model is automatically translated to a Moloni API endpoint. This means the gem supports new Moloni methods as soon as they are released, without code changes.
+
+```ruby
+# These all work immediately, even if not explicitly defined:
+Moloni::Product.getByReference(reference: 'ABC-123')
+Moloni::Product.get_by_reference(reference: 'ABC-123')
+Moloni::Invoice.getByNumber(number: 'FT 2025/001')
+```
+
+### Customers
+
+```ruby
+# Find by VAT, email, or customer number
+customer = Moloni::Customer.getByVat(vat: '123456789')
+customer = Moloni::Customer.find_by_vat(vat: '123456789')
+
+# Create a customer
+customer = Moloni::Customer.insert(
+  name: 'Acme Corp',
+  vat: '123456789',
+  number: 'C001',
+  language_id: 1,
+  address: 'Main St 1',
+  city: 'Lisbon',
+  country_id: 1,
+  maturity_date_id: Moloni::MaturityDate.pronto_pagamento,
+  payment_method_id: Moloni::PaymentMethod.numerario
+)
+```
+
+### Invoices and Documents
+
+```ruby
+# Create an invoice
+invoice = Moloni::Invoice.insert(
+  document_set_id: 332_429,
+  date: Date.today,
+  expiration_date: Date.today + 30,
+  customer_id: 38_096_359,
+  products: [
+    {
+      product_id: 70_241_498,
+      name: 'Consulting',
+      qty: 1,
+      price: 100.00,
+      taxes: [{ tax_id: Moloni::Tax.iva_normal_id }]
+    }
+  ]
+)
+
+# Get PDF link
+pdf_url = Moloni::Document.getPDFLink(document_id: invoice[:document_id])
+```
+
+### Taxes and Settings
+
+```ruby
+# Get hardcoded tax IDs
+normal_iva = Moloni::Tax.iva_normal_id      # 2072734
+intermedio = Moloni::Tax.iva_intermedio_id    # 2072748
+reduzido   = Moloni::Tax.iva_reduzido_id      # 2072741
+
+# Get full tax objects
+normal_tax = Moloni::Tax.iva_normal
+```
+
+## Error Handling
+
+The gem raises specific exceptions for different failure modes:
+
+```ruby
+begin
+  Moloni::Product.getOne(product_id: 999_999)
+rescue Moloni::APIKeyError => e
+  # HTTP 401 — access token invalid or expired
+rescue Moloni::APIError => e
+  # Validation errors (missing fields, invalid format, etc.)
+  e.errors.each do |err|
+    puts "#{err[:field]}: #{err[:message]}"
+  end
+rescue Moloni::TokenExpiredError => e
+  # Both access and refresh tokens expired — re-authentication needed
+end
+```
+
+## Breaking Changes (0.4 → 0.5)
+
+- **Ruby requirement:** Now requires Ruby 3.2 or later.
+- **HTTP method:** All API calls now use `POST` (previously some reads used `GET`).
+- **Removed methods:** Redundant explicit methods (`all`, `count`, `find`, `create`) were removed from models where they offered no custom logic. Use dynamic dispatch (`getAll`, `getOne`, `insert`) instead.
+- **Auth URL fix:** `Moloni::Auth.auth_url` now correctly points to `https://www.moloni.pt/ac/root/oauth/`.
+- **Multi-json removed:** Replaced `multi_json` with standard library `JSON`.
+
+## 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.
+
+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`.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/auth

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+
+require 'dotenv'
+Dotenv.load
+
+require 'moloni'
+require 'moloni/auth'
+require 'moloni/cli/oauth_callback_command'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+Moloni::Cli::OauthCallbackCommand.new(ENV['DEVELOPER_ID'], ENV['CLIENT_SECRET']).run

data/bin/console

@@ -0,0 +1,34 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'moloni'
+
+require 'dotenv'
+Dotenv.load
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+Moloni.configure do |config|
+  config.developer_id = ENV['DEVELOPER_ID']
+  config.redirect_uri = ENV['REDIRECT_URI']
+  config.client_secret = ENV['CLIENT_SECRET']
+  config.refresh_token = ENV['REFRESH_TOKEN']
+  config.access_token = ENV['ACCESS_TOKEN']
+  config.company_id = ENV['COMPANY_ID']
+  config.debug = true
+end
+
+# Allow direct access to Moloni classes
+send(:include, Moloni)
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+# require 'irb'
+# IRB.start(__FILE__)
+
+require 'pry'
+Pry.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/moloni/auth.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'addressable'
+require 'json'
+
+module Moloni
+  class Auth
+    WEB_AUTH_URL = 'https://www.moloni.pt/ac/root/oauth/'
+    API_TOKEN_PATH = 'grant/'
+
+    def initialize
+      @config = Moloni.config
+      @api_domain = API_BASE_URL
+    end
+
+    def self.auth_url
+      new.auth_url
+    end
+
+    def auth_url
+      uri = Addressable::URI.parse(WEB_AUTH_URL)
+
+      query = {
+        response_type: 'code',
+        client_id: @config.developer_id,
+        redirect_uri: @config.redirect_uri
+      }
+
+      uri.query_values = query
+
+      Addressable::URI.unencode(uri.to_s)
+    end
+
+    def token_full_uri
+      Addressable::URI.join(API_BASE_URL, API_TOKEN_PATH)
+    end
+
+    def self.get_tokens(authorization_code)
+      new.get_token(authorization_code)
+    end
+
+    def get_token(authorization_code)
+      result = Faraday.get(get_access_token_url(authorization_code))
+
+      parse_and_update(result.body)
+    end
+
+    def get_access_token_url(authorization_code)
+      uri = token_full_uri
+
+      uri.query_values = {
+        client_id: @config.developer_id,
+        client_secret: @config.client_secret,
+        code: authorization_code,
+        redirect_uri: @config.redirect_uri,
+        grant_type: 'authorization_code'
+      }
+
+      Addressable::URI.unencode(uri.to_s)
+    end
+
+    def self.refresh_tokens(refresh_token = nil)
+      new.refresh_tokens(refresh_token)
+    end
+
+    def refresh_tokens(refresh_token = nil)
+      token = refresh_token || @config.refresh_token
+
+      raise TokenExpiredError, 'Refresh token is missing or expired' if token.nil? || token.empty?
+      raise TokenExpiredError, 'Refresh token has expired' if @config.refresh_token_expired?
+
+      result = Faraday.get(refresh_tokens_url(token))
+
+      parse_and_update(result.body)
+    end
+
+    def refresh_tokens_url(refresh_token)
+      uri = token_full_uri
+
+      uri.query_values = {
+        client_id: @config.developer_id,
+        client_secret: @config.client_secret,
+        refresh_token:,
+        grant_type: 'refresh_token'
+      }
+
+      Addressable::URI.unencode(uri.to_s)
+    end
+
+    private
+
+    def parse_and_update(body)
+      parsed = JSON.parse(body, symbolize_names: true)
+
+      raise APIError, "#{parsed[:error]}: #{parsed[:error_description]}" if parsed[:error]
+
+      @config.access_token = parsed[:access_token]
+      @config.refresh_token = parsed[:refresh_token]
+      @config.access_token_expires_at = Time.now + (parsed[:expires_in] || 3600)
+      @config.refresh_token_expires_at = Time.now + (14 * 24 * 60 * 60) # 14 days
+
+      parsed
+    end
+  end
+end

data/lib/moloni/base_model.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require 'addressable'
+require 'json'
+
+require 'moloni/errors'
+
+module Moloni
+  class BaseModel
+    @intermediate_path = ''
+
+    class << self
+      attr_accessor :intermediate_path
+    end
+
+    def self.format_url(url, params)
+      formatted = url.dup.strip
+
+      params.each { |key, value| formatted.sub!(":#{key}", value.to_s) }
+
+      formatted
+    end
+
+    def format_url(url, params)
+      self.class.format_url(url, params)
+    end
+
+    def self.post(method_path, opts = {})
+      ensure_token_valid!
+
+      full_uri = build_full_uri(method_path)
+      full_params = composed_params(opts)
+
+      result = api_post(full_uri.to_s, full_params)
+
+      parse_response(result)
+    end
+
+    def self.composed_params(opts)
+      trimmed_opts = opts.compact
+      {
+        company_id: Moloni.config.company_id
+      }.merge(trimmed_opts)
+    end
+
+    # Dynamic dispatch for any Moloni API method.
+    # Examples:
+    #   Product.getByEAN(ean: '123')
+    #   Product.get_by_ean(ean: '123')  # snake_case alias
+    #   Invoice.insert(args)
+    def self.method_missing(method_name, *args, &_block)
+      args = [{}] if args.empty?
+      camelized_method = camelize_method_name(method_name.to_s)
+      post("#{camelized_method}/", args.first || {})
+    end
+
+    def self.respond_to_missing?(_method_name, _include_private = false)
+      true
+    end
+
+    # Backward-compatible aliases for generic CRUD operations.
+    # These map common Ruby method names to the actual Moloni API endpoints.
+    def self.all(args = {})
+      post('getAll/', args)
+    end
+
+    def self.find(args = {})
+      post('getOne/', args)
+    end
+
+    def self.count(args = {})
+      post('count/', args)
+    end
+
+    def self.create(args = {})
+      post('insert/', args)
+    end
+
+    def self.delete(args = {})
+      post('delete/', args)
+    end
+
+    private_class_method def self.ensure_token_valid!
+      return unless Moloni.config.access_token_expired?
+
+      if Moloni.config.refresh_token_expired?
+        raise TokenExpiredError,
+              'Access token expired and refresh token is no longer valid. ' \
+              'Re-authentication required.'
+      end
+
+      Auth.refresh_tokens
+    end
+
+    private_class_method def self.build_full_uri(method_path)
+      full_uri = Addressable::URI.join(intermediate_path, method_path)
+      full_uri.query_values = {
+        json: 'true',
+        human_errors: 'true',
+        access_token: Moloni.config.access_token
+      }
+      full_uri
+    end
+
+    private_class_method def self.api_post(path_uri, opts = {})
+      request_path = Addressable::URI.unencode(path_uri)
+      Moloni.connection.post(request_path, JSON.generate(opts))
+    end
+
+    private_class_method def self.parse_response(result)
+      raise APIKeyError, result.body[:error] if result.status == 401
+
+      body = result.body
+
+      # Data validation errors come as an array of strings like "1 name"
+      if body.is_a?(Array) && body.any? { |e| e.is_a?(String) && e.match?(/\A\d+\s+/) }
+        errors = body.map { |raw| parse_validation_error(raw) }
+        messages = errors.map { |e| "#{e[:field]}: #{e[:message]}" }.join(', ')
+        error = APIError.new("Validation failed: #{messages}", errors)
+        raise error
+      end
+
+      body
+    end
+
+    ERROR_MESSAGES = {
+      1 => 'is required',
+      2 => 'must be numeric',
+      3 => 'must be a valid email',
+      4 => 'must be unique',
+      5 => 'must be one of accepted values',
+      6 => 'must be a valid URL',
+      7 => 'must be a valid postal code',
+      8 => 'must be a valid Portuguese VAT number',
+      9 => 'must be a date in YYYY-mm-dd format',
+      10 => 'has an invalid document association',
+      11 => 'cannot be sent to Tax Authority',
+      12 => 'has an invalid date comparison',
+      13 => 'must be a valid phone contact',
+      14 => 'has invalid tax configuration',
+      15 => 'has more than one VAT',
+      16 => 'customer identification does not meet legal requirements',
+      17 => 'field limit reached'
+    }.freeze
+
+    private_class_method def self.parse_validation_error(raw)
+      parts = raw.to_s.split
+      code = parts[0].to_i
+      field = parts[1]
+      params = parts[2..]
+
+      message = ERROR_MESSAGES[code] || 'is invalid'
+      message += " (#{params.join(', ')})" if code == 2 && params.any?
+
+      { code:, field:, message:, raw: }
+    end
+
+    COMMON_ACRONYMS = %w[ean sku nif iban].freeze
+
+    private_class_method def self.camelize_method_name(name)
+      return name unless name.include?('_')
+
+      name.split('_').each_with_index.map do |part, index|
+        if index.zero?
+          part
+        elsif COMMON_ACRONYMS.include?(part)
+          part.upcase
+        else
+          part.capitalize
+        end
+      end.join
+    end
+  end
+end

data/lib/moloni/cli/oauth_callback_command.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require 'launchy'
+
+require 'moloni'
+require 'moloni/cli/oauth_callback_server'
+
+require 'dotenv'
+Dotenv.load
+
+module Moloni
+  module Cli
+    class OauthCallbackCommand
+      def initialize(developer_id, client_secret)
+        @options = {
+          port: default_port,
+          client_secret:,
+          developer_id:
+        }
+      end
+
+      def default_port
+        Moloni::Cli::OauthCallbackServer.settings.port
+      end
+
+      def run(_argv = ARGV, _env = ENV)
+        Moloni::Cli::OauthCallbackServer.set(:port, @options[:port]) if @options[:port]
+
+        callback_path = Moloni::Cli::OauthCallbackServer::CALLBACK_PATH
+        bind_port = Moloni::Cli::OauthCallbackServer.settings.port
+        bind_address = Moloni::Cli::OauthCallbackServer.settings.bind
+
+        callback_url = "http://#{bind_address}:#{bind_port}/#{callback_path}"
+
+        Moloni.configure do |config|
+          config.developer_id = @options[:developer_id] || ENV['DEVELOPER_ID']
+          config.redirect_uri = ENV['REDIRECT_URI']
+          config.client_secret = @options[:client_secret] || ENV['CLIENT_SECRET']
+          config.debug = true
+        end
+
+        url = Moloni::Auth.auth_url
+
+        puts "Callback URL: #{callback_url}"
+        puts "Open this url to authenticate: #{url}"
+
+        Launchy.open(url)
+
+        puts 'Running callback server....'
+        Moloni::Cli::OauthCallbackServer.run!
+      end
+    end
+  end
+end

data/lib/moloni/cli/oauth_callback_server.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'sinatra/base'
+
+module Moloni
+  module Cli
+    class OauthCallbackServer < Sinatra::Base
+      enable :logging
+
+      CALLBACK_PATH = 'oauth2callback'
+
+      get "/#{CALLBACK_PATH}" do
+        grant_token = params[:code]
+
+        # This will trigger a post request to get both the token and the refresh token
+        @variables = Moloni::Auth.get_tokens(grant_token)
+
+        puts "Variables: #{@variables.inspect}"
+
+        erb :variables
+      end
+    end
+  end
+end

data/lib/moloni/cli/views/variables.erb

@@ -0,0 +1,80 @@
+<!DOCTYPE html>
+<html lang="en" dir="ltr">
+  <head>
+    <meta charset="utf-8">
+    <title>Moloni OAuth2 Dev Server</title>
+    <style media="screen">
+      body {
+        font-family: sans-serif;
+        padding: 20px 50px;
+      }
+
+      ul.variables {
+        padding: 20px;
+        background-color: #eaeaea;
+        font-family: monospace;
+        list-style: none;
+        line-height: 1.5em;
+        margin-bottom: 50px;
+      }
+
+      li.error {
+        color: #aa0000;
+      }
+
+      div.config {
+        padding: 20px;
+        background-color: #eaeaea;
+        font-family: monospace;
+        line-height: 1.5em;
+      }
+
+      pre {
+        margin: 0;
+        padding: 0;
+      }
+
+      code {
+        padding: 0;
+        margin: 0;
+      }
+
+      footer {
+        margin-top: 60px;
+        font-size: .8em;
+      }
+    </style>
+  </head>
+
+  <body>
+    <h2>Here's what you have to add to your environment variables:</h2>
+
+    <ul class="variables">
+      <li>DEVELOPER_ID=<%= Moloni.config.developer_id %></li>
+      <li>CLIENT_SECRET=<%= Moloni.config.client_secret %></li>
+      
+      <% if @variables[:refresh_token] %>
+      <li>REFRESH_TOKEN=<%= @variables[:refresh_token] %></li>
+      <% else %>
+      <li class="error">REFRESH_TOKEN=Moloni didn't send a REFRESH_TOKEN</li>
+      <% end %>
+
+      <% if @variables[:access_token] %>
+      <li>ACCESS_TOKEN=<%= @variables[:access_token] %></li>
+      <% else %>
+      <li class="error">ACCESS_TOKEN=Moloni didn't send a ACCESS_TOKEN</li>
+      <% end %>
+    </ul>
+
+    <h2>Then you need a configuration block like this one:</h2>
+    <div class="config">
+      <pre><code>Moloni.configure do |config|
+  config.developer_id   = ENV['DEVELOPER_ID']
+  config.client_secret  = ENV['CLIENT_SECRET']
+  config.refresh_token  = ENV['REFRESH_TOKEN']
+end</code></pre>
+    </div>
+
+    <footer>Moloni Rubygem v<%= Moloni::VERSION %></footer>
+  </body>
+</html>