factpulse 0.1.0 → 1.0.0

data/lib/factpulse/helpers/client.rb

@@ -1,271 +1,299 @@
 # frozen_string_literal: true
-#
-# FactPulse SDK - Thin HTTP wrapper with auto-polling.
-#
-# Usage:
-#   client = FactPulseClient.new('email', 'password', 'client_uid')
-#
-#   # POST /api/v1/processing/invoices/submit-complete-async
-#   result = client.post('processing/invoices/submit-complete-async',
-#     invoiceData: {...},
-#     destination: { type: 'afnor' }
-#   )
-#   pdf_bytes = result['content'] # auto-decoded, auto-polled
-
-require 'net/http'
-require 'json'
-require 'base64'
-require 'uri'
+require 'net/http'; require 'json'; require 'base64'; require 'uri'; require 'securerandom'
 
 module FactPulse
-  class Error < StandardError
-    attr_reader :status_code, :details
-
-    def initialize(message, status_code: nil, details: [])
-      super(message)
-      @status_code = status_code
-      @details = details
-    end
-  end
-
-  class Client
-    DEFAULT_API_URL = 'https://factpulse.fr'
-
-    def initialize(email, password, client_uid, api_url: DEFAULT_API_URL, timeout: 60, polling_timeout: 120)
-      @email = email
-      @password = password
-      @client_uid = client_uid
-      @api_url = api_url.chomp('/')
-      @timeout = timeout
-      @polling_timeout = polling_timeout
-      @token = nil
-      @token_expires_at = 0
-      @token_mutex = Mutex.new
-    end
-
-    # POST request to /api/v1/{path} (JSON body)
-    def post(path, **data)
-      request('POST', path, data, retry_auth: true)
-    end
-
-    # POST request with multipart/form-data (for file uploads)
-    def post_multipart(path, data: {}, files: {})
-      request_multipart(path, data, files, retry_auth: true)
+  module Helpers
+    # Credentials Chorus Pro pour le mode Zero-Trust.
+    # Ces credentials sont passés dans chaque requête et ne sont jamais stockés côté serveur.
+    class ChorusProCredentials
+      attr_reader :piste_client_id, :piste_client_secret, :chorus_pro_login, :chorus_pro_password, :sandbox
+      def initialize(piste_client_id:, piste_client_secret:, chorus_pro_login:, chorus_pro_password:, sandbox: true)
+        @piste_client_id, @piste_client_secret = piste_client_id, piste_client_secret
+        @chorus_pro_login, @chorus_pro_password, @sandbox = chorus_pro_login, chorus_pro_password, sandbox
+      end
+      def to_h
+        { 'piste_client_id' => @piste_client_id, 'piste_client_secret' => @piste_client_secret,
+          'chorus_pro_login' => @chorus_pro_login, 'chorus_pro_password' => @chorus_pro_password, 'sandbox' => @sandbox }
+      end
     end
 
-    # GET request to /api/v1/{path}
-    def get(path, **params)
-      request('GET', path, params, retry_auth: true)
+    # Credentials AFNOR PDP pour le mode Zero-Trust.
+    # L'API FactPulse utilise ces credentials pour s'authentifier auprès de la PDP AFNOR.
+    class AFNORCredentials
+      attr_reader :flow_service_url, :token_url, :client_id, :client_secret, :directory_service_url
+      def initialize(flow_service_url:, token_url:, client_id:, client_secret:, directory_service_url: nil)
+        @flow_service_url, @token_url = flow_service_url, token_url
+        @client_id, @client_secret, @directory_service_url = client_id, client_secret, directory_service_url
+      end
+      def to_h
+        result = { 'flow_service_url' => @flow_service_url, 'token_url' => @token_url,
+                   'client_id' => @client_id, 'client_secret' => @client_secret }
+        result['directory_service_url'] = @directory_service_url if @directory_service_url
+        result
+      end
     end
 
-    private
-
-    def request(method, path, data, retry_auth:)
-      ensure_auth
-      url = "#{@api_url}/api/v1/#{path}"
-      uri = URI(url)
-
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == 'https'
-      http.read_timeout = @timeout
-
-      if method == 'POST'
-        req = Net::HTTP::Post.new(uri)
-        req['Content-Type'] = 'application/json'
-        req.body = JSON.generate(data)
-      else
-        uri.query = URI.encode_www_form(data) unless data.empty?
-        req = Net::HTTP::Get.new(uri)
+    # Helpers pour créer des montants totaux simplifiés.
+    module MontantHelpers
+      def self.montant(value)
+        return '0.00' if value.nil?
+        return format('%.2f', value) if value.is_a?(Numeric)
+        value.is_a?(String) ? value : '0.00'
       end
-      req['Authorization'] = "Bearer #{@token}"
 
-      response = http.request(req)
-
-      if response.code == '401' && retry_auth
-        invalidate_token
-        return request(method, path, data, retry_auth: false)
+      def self.montant_total(ht, tva, ttc, a_payer, remise_ttc: nil, motif_remise: nil, acompte: nil)
+        result = {
+          'montantHtTotal' => montant(ht), 'montantTva' => montant(tva),
+          'montantTtcTotal' => montant(ttc), 'montantAPayer' => montant(a_payer)
+        }
+        result['montantRemiseGlobaleTtc'] = montant(remise_ttc) if remise_ttc
+        result['motifRemiseGlobaleTtc'] = motif_remise if motif_remise
+        result['acompte'] = montant(acompte) if acompte
+        result
       end
 
-      result = parse_response(response)
-
-      # Auto-poll: support both taskId (camelCase) and task_id (snake_case)
-      if result.is_a?(Hash)
-        task_id = result['taskId'] || result['task_id']
-        result = poll(task_id) if task_id
+      # Crée une ligne de poste (aligné sur LigneDePoste de models.py).
+      def self.ligne_de_poste(numero, denomination, quantite, montant_unitaire_ht, montant_total_ligne_ht,
+                              taux_tva: '20.00', categorie_tva: 'S', unite: 'FORFAIT', **options)
+        result = {
+          'numero' => numero, 'denomination' => denomination,
+          'quantite' => montant(quantite), 'montantUnitaireHt' => montant(montant_unitaire_ht),
+          'montantTotalLigneHt' => montant(montant_total_ligne_ht), 'tauxTva' => montant(taux_tva),
+          'categorieTva' => categorie_tva, 'unite' => unite
+        }
+        result['reference'] = options[:reference] if options[:reference]
+        result['montantRemiseHt'] = montant(options[:montant_remise_ht]) if options[:montant_remise_ht]
+        result['codeRaisonReduction'] = options[:code_raison_reduction] if options[:code_raison_reduction]
+        result['raisonReduction'] = options[:raison_reduction] if options[:raison_reduction]
+        result['dateDebutPeriode'] = options[:date_debut_periode] if options[:date_debut_periode]
+        result['dateFinPeriode'] = options[:date_fin_periode] if options[:date_fin_periode]
+        result
       end
 
-      # Auto-decode: support both content_b64 and contentB64
-      if result.is_a?(Hash)
-        b64_content = result.delete('content_b64') || result.delete('contentB64')
-        result['content'] = Base64.decode64(b64_content) if b64_content
+      # Crée une ligne de TVA (aligné sur LigneDeTVA de models.py).
+      def self.ligne_de_tva(taux_manuel, montant_base_ht, montant_tva, categorie: 'S')
+        {
+          'tauxManuel' => montant(taux_manuel), 'montantBaseHt' => montant(montant_base_ht),
+          'montantTva' => montant(montant_tva), 'categorie' => categorie
+        }
       end
 
-      result
-    end
-
-    def request_multipart(path, data, files, retry_auth:)
-      ensure_auth
-      url = "#{@api_url}/api/v1/#{path}"
-      uri = URI(url)
-
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == 'https'
-      http.read_timeout = @timeout
-
-      # Build multipart body
-      boundary = "----RubyFormBoundary#{rand(1_000_000)}"
-      body = []
-
-      data.each do |key, value|
-        body << "--#{boundary}\r\n"
-        body << "Content-Disposition: form-data; name=\"#{key}\"\r\n\r\n"
-        body << "#{value}\r\n"
+      # Crée une adresse postale pour l'API FactPulse.
+      def self.adresse_postale(ligne1, code_postal, ville, pays: 'FR', ligne2: nil, ligne3: nil)
+        result = { 'ligneUn' => ligne1, 'codePostal' => code_postal, 'nomVille' => ville, 'paysCodeIso' => pays }
+        result['ligneDeux'] = ligne2 if ligne2
+        result['ligneTrois'] = ligne3 if ligne3
+        result
       end
 
-      files.each do |key, content|
-        body << "--#{boundary}\r\n"
-        body << "Content-Disposition: form-data; name=\"#{key}\"; filename=\"#{key}\"\r\n"
-        body << "Content-Type: application/octet-stream\r\n\r\n"
-        body << content
-        body << "\r\n"
+      # Crée une adresse électronique. scheme_id: "0009"=SIREN, "0225"=SIRET
+      def self.adresse_electronique(identifiant, scheme_id: '0009')
+        { 'identifiant' => identifiant, 'schemeId' => scheme_id }
       end
 
-      body << "--#{boundary}--\r\n"
-
-      req = Net::HTTP::Post.new(uri)
-      req['Authorization'] = "Bearer #{@token}"
-      req['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
-      req.body = body.join
-
-      response = http.request(req)
-
-      if response.code == '401' && retry_auth
-        invalidate_token
-        return request_multipart(path, data, files, retry_auth: false)
+      # Calcule le numéro TVA intracommunautaire français depuis un SIREN.
+      def self.calculer_tva_intra(siren)
+        return nil if siren.nil? || siren.length != 9 || !siren.match?(/^\d+$/)
+        cle = (12 + 3 * (siren.to_i % 97)) % 97
+        format('FR%02d%s', cle, siren)
       end
 
-      result = parse_response(response)
-
-      # Auto-poll
-      if result.is_a?(Hash)
-        task_id = result['taskId'] || result['task_id']
-        result = poll(task_id) if task_id
+      # Crée un fournisseur (émetteur) avec auto-calcul SIREN, TVA intracommunautaire et adresses.
+      def self.fournisseur(nom, siret, adresse_ligne1, code_postal, ville, **options)
+        siren = options[:siren] || (siret.length == 14 ? siret[0, 9] : nil)
+        numero_tva_intra = options[:numero_tva_intra] || (siren ? calculer_tva_intra(siren) : nil)
+        result = {
+          'nom' => nom, 'idFournisseur' => options[:id_fournisseur] || 0, 'siret' => siret,
+          'adresseElectronique' => adresse_electronique(siret, scheme_id: '0225'),
+          'adressePostale' => adresse_postale(adresse_ligne1, code_postal, ville, pays: options[:pays] || 'FR', ligne2: options[:adresse_ligne2])
+        }
+        result['siren'] = siren if siren
+        result['numeroTvaIntra'] = numero_tva_intra if numero_tva_intra
+        result['iban'] = options[:iban] if options[:iban]
+        result['idServiceFournisseur'] = options[:code_service] if options[:code_service]
+        result['codeCoordonnesBancairesFournisseur'] = options[:code_coordonnees_bancaires] if options[:code_coordonnees_bancaires]
+        result
       end
 
-      # Auto-decode
-      if result.is_a?(Hash)
-        b64_content = result.delete('content_b64') || result.delete('contentB64')
-        result['content'] = Base64.decode64(b64_content) if b64_content
+      # Crée un destinataire (client) avec auto-calcul SIREN et adresses.
+      def self.destinataire(nom, siret, adresse_ligne1, code_postal, ville, **options)
+        siren = options[:siren] || (siret.length == 14 ? siret[0, 9] : nil)
+        result = {
+          'nom' => nom, 'siret' => siret,
+          'adresseElectronique' => adresse_electronique(siret, scheme_id: '0225'),
+          'adressePostale' => adresse_postale(adresse_ligne1, code_postal, ville, pays: options[:pays] || 'FR', ligne2: options[:adresse_ligne2])
+        }
+        result['siren'] = siren if siren
+        result['codeServiceExecutant'] = options[:code_service_executant] if options[:code_service_executant]
+        result
       end
-
-      result
     end
 
-    def parse_response(response)
-      body = response.body
-      data = body && !body.empty? ? JSON.parse(body) : {}
+    class FactPulseClient
+      attr_reader :chorus_credentials, :afnor_credentials
 
-      return data if response.is_a?(Net::HTTPSuccess)
+      def initialize(email:, password:, api_url: nil, client_uid: nil, chorus_credentials: nil, afnor_credentials: nil,
+                     polling_interval: nil, polling_timeout: nil, max_retries: nil)
+        @email, @password = email, password; @api_url = (api_url || 'https://factpulse.fr').chomp('/')
+        @client_uid, @polling_interval, @polling_timeout, @max_retries = client_uid, polling_interval || 2000, polling_timeout || 120000, max_retries || 1
+        @chorus_credentials, @afnor_credentials = chorus_credentials, afnor_credentials
+        @access_token = @refresh_token = @token_expires_at = nil
+      end
 
-      msg = "HTTP #{response.code}"
-      details = []
+      def chorus_credentials_for_api; @chorus_credentials&.to_h; end
+      def afnor_credentials_for_api; @afnor_credentials&.to_h; end
+      # Alias plus courts
+      def get_chorus_pro_credentials; chorus_credentials_for_api; end
+      def get_afnor_credentials; afnor_credentials_for_api; end
+
+      def ensure_authenticated(force_refresh: false)
+        now = (Time.now.to_f * 1000).to_i
+        if force_refresh || @access_token.nil? || (@token_expires_at && now >= @token_expires_at)
+          payload = { 'username' => @email, 'password' => @password }; payload['client_uid'] = @client_uid if @client_uid
+          response = http_post(URI("#{@api_url}/api/token/"), payload)
+          raise FactPulseAuthError, "Auth failed" unless response.is_a?(Net::HTTPSuccess)
+          tokens = JSON.parse(response.body); @access_token, @refresh_token = tokens['access'], tokens['refresh']
+          @token_expires_at = now + (28 * 60 * 1000)
+        end
+      end
 
-      if data.is_a?(Hash)
-        if data['detail'].is_a?(Array)
-          details = data['detail']
-          msgs = data['detail'].map do |e|
-            loc = e['loc'] || []
-            "#{loc.last || '?'}: #{e['msg'] || '?'}"
+      def reset_auth; @access_token = @refresh_token = @token_expires_at = nil; end
+
+      def poll_task(task_id, timeout: nil, interval: nil)
+        timeout_ms, interval_ms = timeout || @polling_timeout, interval || @polling_interval
+        start_time, current_interval = (Time.now.to_f * 1000).to_i, interval_ms.to_f
+        loop do
+          raise FactPulsePollingTimeout.new(task_id, timeout_ms) if (Time.now.to_f * 1000).to_i - start_time > timeout_ms
+          ensure_authenticated; response = http_get(URI("#{@api_url}/api/v1/traitement/taches/#{task_id}/statut"))
+          reset_auth and next if response.code == '401'
+          data = JSON.parse(response.body)
+          return data['resultat'] || {} if data['statut'] == 'SUCCESS'
+          if data['statut'] == 'FAILURE'
+            r = data['resultat'] || {}
+            raise FactPulseValidationError.new("Task #{task_id} failed: #{r['message_erreur'] || '?'}", (r['erreurs'] || []).map { |e| ValidationErrorDetail.from_hash(e) })
           end
-          msg = "Validation error: #{msgs.join('; ')}"
-        elsif data['detail'].is_a?(String)
-          msg = data['detail']
-        elsif data['errorMessage'].is_a?(String)
-          msg = data['errorMessage']
+          sleep(current_interval / 1000.0); current_interval = [current_interval * 1.5, 10000].min
         end
       end
 
-      raise Error.new(msg, status_code: response.code.to_i, details: details)
-    end
+      def self.format_montant(m); MontantHelpers.montant(m); end
+
+      # Génère une facture Factur-X à partir d'un dict/hash et d'un PDF source.
+      # Accepte un Hash, un String JSON, ou tout objet avec une méthode to_h/to_hash.
+      # @param facture_data [Hash, String, Object] Données de la facture
+      # @param pdf_source [String, File] Chemin vers le PDF source ou objet File
+      # @param profil [String] Profil Factur-X (MINIMUM, BASIC, EN16931, EXTENDED)
+      # @param format_sortie [String] Format de sortie (pdf, xml, both)
+      # @param sync [Boolean] Mode synchrone (true) ou asynchrone (false)
+      # @param timeout [Integer, nil] Timeout en ms pour le polling
+      # @return [String] Contenu binaire du PDF généré
+      def generer_facturx(facture_data, pdf_source, profil: 'EN16931', format_sortie: 'pdf', sync: true, timeout: nil)
+        # Conversion des données en JSON string
+        json_data = case facture_data
+                    when String then facture_data
+                    when Hash then JSON.generate(facture_data)
+                    else
+                      if facture_data.respond_to?(:to_h)
+                        JSON.generate(facture_data.to_h)
+                      elsif facture_data.respond_to?(:to_hash)
+                        JSON.generate(facture_data.to_hash)
+                      else
+                        raise FactPulseValidationError.new("Type de données non supporté: #{facture_data.class}")
+                      end
+                    end
+
+        # Lecture du PDF source
+        pdf_content = case pdf_source
+                      when String then File.binread(pdf_source)
+                      when File then pdf_source.read
+                      else
+                        if pdf_source.respond_to?(:read)
+                          pdf_source.read
+                        else
+                          raise FactPulseValidationError.new("Type de PDF non supporté: #{pdf_source.class}")
+                        end
+                      end
+        pdf_filename = pdf_source.is_a?(String) ? File.basename(pdf_source) : 'facture.pdf'
+
+        ensure_authenticated
+        uri = URI("#{@api_url}/api/v1/traitement/generer-facture")
+
+        # Construire la requête multipart
+        boundary = "----RubyFormBoundary#{SecureRandom.hex(16)}"
+        body = []
+
+        # Champ donnees_facture
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"donnees_facture\"\r\n\r\n"
+        body << "#{json_data}\r\n"
+
+        # Champ profil
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"profil\"\r\n\r\n"
+        body << "#{profil}\r\n"
 
-    def poll(task_id)
-      start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      interval = 1.0
+        # Champ format_sortie
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"format_sortie\"\r\n\r\n"
+        body << "#{format_sortie}\r\n"
 
-      loop do
-        elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
-        if elapsed >= @polling_timeout
-          raise Error.new("Polling timeout after #{@polling_timeout}s for task #{task_id}")
-        end
+        # Champ source_pdf (fichier)
+        body << "--#{boundary}\r\n"
+        body << "Content-Disposition: form-data; name=\"source_pdf\"; filename=\"#{pdf_filename}\"\r\n"
+        body << "Content-Type: application/pdf\r\n\r\n"
+        body << pdf_content
+        body << "\r\n"
+
+        body << "--#{boundary}--\r\n"
+        body_str = body.join
 
-        ensure_auth
-        uri = URI("#{@api_url}/api/v1/processing/tasks/#{task_id}/status")
         http = Net::HTTP.new(uri.host, uri.port)
         http.use_ssl = uri.scheme == 'https'
-        http.read_timeout = @timeout
-
-        req = Net::HTTP::Get.new(uri)
-        req['Authorization'] = "Bearer #{@token}"
-        response = http.request(req)
+        http.read_timeout = 120
 
-        if response.code == '401'
-          invalidate_token
-          next
-        end
+        request = Net::HTTP::Post.new(uri)
+        request['Authorization'] = "Bearer #{@access_token}"
+        request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
+        request.body = body_str
 
-        data = parse_response(response)
-        status = data['status']
+        response = http.request(request)
 
-        if status == 'SUCCESS'
-          result = data['result'] || {}
-          # Support both content_b64 and contentB64
-          b64_content = result.delete('content_b64') || result.delete('contentB64')
-          result['content'] = Base64.decode64(b64_content) if b64_content
-          return result
+        if response.code == '401'
+          reset_auth
+          ensure_authenticated
+          request['Authorization'] = "Bearer #{@access_token}"
+          response = http.request(request)
         end
 
-        if status == 'FAILURE'
-          res = data['result'] || {}
-          raise Error.new(res['errorMessage'] || 'Task failed', details: res['details'] || [])
+        unless response.is_a?(Net::HTTPSuccess)
+          error_data = JSON.parse(response.body) rescue { 'detail' => response.body }
+          raise FactPulseValidationError.new("Erreur API: #{error_data['detail'] || response.body}")
         end
 
-        sleep([interval, @polling_timeout - elapsed].min)
-        interval = [interval * 1.5, 10].min
-      end
-    end
+        data = JSON.parse(response.body)
 
-    def ensure_auth
-      @token_mutex.synchronize do
-        if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= @token_expires_at
-          refresh_token
+        if sync && data['id_tache']
+          result = poll_task(data['id_tache'], timeout: timeout)
+          if result['contenu_b64']
+            require 'base64'
+            return Base64.decode64(result['contenu_b64'])
+          elsif result['contenu_xml']
+            return result['contenu_xml']
+          end
+          raise FactPulseValidationError.new("Résultat inattendu: #{result.keys.join(', ')}")
         end
-      end
-    end
-
-    def refresh_token
-      uri = URI("#{@api_url}/api/token/")
-      http = Net::HTTP.new(uri.host, uri.port)
-      http.use_ssl = uri.scheme == 'https'
-      http.read_timeout = @timeout
-
-      req = Net::HTTP::Post.new(uri)
-      req['Content-Type'] = 'application/json'
-      req.body = JSON.generate(username: @email, password: @password, client_uid: @client_uid)
-
-      response = http.request(req)
 
-      unless response.is_a?(Net::HTTPSuccess)
-        raise Error.new("Authentication failed: HTTP #{response.code}", status_code: response.code.to_i)
+        data
       end
 
-      data = JSON.parse(response.body)
-      @token = data['access'] || raise(Error.new('Invalid auth response'))
-      @token_expires_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 28 * 60
-    end
-
-    def invalidate_token
-      @token_mutex.synchronize do
-        @token_expires_at = 0
+      private
+      def http_post(uri, payload)
+        Net::HTTP.new(uri.host, uri.port).tap { |h| h.use_ssl = uri.scheme == 'https'; h.read_timeout = 30 }
+          .request(Net::HTTP::Post.new(uri).tap { |r| r['Content-Type'] = 'application/json'; r.body = JSON.generate(payload) })
+      end
+      def http_get(uri)
+        Net::HTTP.new(uri.host, uri.port).tap { |h| h.use_ssl = uri.scheme == 'https'; h.read_timeout = 30 }
+          .request(Net::HTTP::Get.new(uri).tap { |r| r['Authorization'] = "Bearer #{@access_token}" })
       end
     end
   end

data/lib/factpulse/helpers/exceptions.rb

@@ -1,45 +1,21 @@
 # frozen_string_literal: true
-
 module FactPulse
-  # Additional error types (base Error class is in client.rb)
-  class AuthError < Error; end
-
-  class PollingTimeout < Error
-    attr_reader :task_id, :timeout
-
-    def initialize(task_id, timeout)
-      @task_id = task_id
-      @timeout = timeout
-      super("Timeout (#{timeout}ms) for #{task_id}")
+  module Helpers
+    class FactPulseError < StandardError; end
+    class FactPulseAuthError < FactPulseError; end
+    class FactPulsePollingTimeout < FactPulseError
+      attr_reader :task_id, :timeout
+      def initialize(task_id, timeout); @task_id, @timeout = task_id, timeout; super("Timeout (#{timeout}ms) pour #{task_id}"); end
     end
-  end
-
-  class ValidationErrorDetail
-    attr_accessor :level, :item, :reason, :source, :code
-
-    def initialize(level: '', item: '', reason: '', source: nil, code: nil)
-      @level = level
-      @item = item
-      @reason = reason
-      @source = source
-      @code = code
-    end
-
-    def to_s
-      "[#{@item.to_s.empty? ? 'unknown' : @item}] #{@reason.to_s.empty? ? 'Unknown error' : @reason}"
+    class ValidationErrorDetail
+      attr_accessor :level, :item, :reason, :source, :code
+      def initialize(level: '', item: '', reason: '', source: nil, code: nil); @level, @item, @reason, @source, @code = level, item, reason, source, code; end
+      def to_s; "[#{@item.to_s.empty? ? 'unknown' : @item}] #{@reason.to_s.empty? ? 'Unknown error' : @reason}"; end
+      def self.from_hash(h); new(level: h['level']||'', item: h['item']||'', reason: h['reason']||'', source: h['source'], code: h['code']); end
     end
-
-    def self.from_hash(h)
-      new(level: h['level'] || '', item: h['item'] || '', reason: h['reason'] || '', source: h['source'], code: h['code'])
-    end
-  end
-
-  class ValidationError < Error
-    attr_reader :errors
-
-    def initialize(msg, errors = [])
-      @errors = errors
-      super(errors.empty? ? msg : "#{msg}\n\nDetails:\n#{errors.map { |e| "  - #{e}" }.join("\n")}")
+    class FactPulseValidationError < FactPulseError
+      attr_reader :errors
+      def initialize(msg, errors = []); @errors = errors; super(errors.empty? ? msg : "#{msg}\n\nDétails:\n#{errors.map{|e| "  - #{e}"}.join("\n")}"); end
     end
   end
 end

data/lib/factpulse/helpers.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+require_relative 'helpers/exceptions'
+require_relative 'helpers/client'
+module FactPulse
+  module Helpers
+    def self.create_client(**opts); FactPulseClient.new(**opts); end
+    def self.format_montant(m); MontantHelpers.montant(m); end
+    def self.montant(m); MontantHelpers.montant(m); end
+    def self.montant_total(*args, **kwargs); MontantHelpers.montant_total(*args, **kwargs); end
+    def self.ligne_de_poste(*args, **kwargs); MontantHelpers.ligne_de_poste(*args, **kwargs); end
+    def self.ligne_de_tva(*args, **kwargs); MontantHelpers.ligne_de_tva(*args, **kwargs); end
+  end
+end