cpro-client 0.1.0

data/lib/cpro/facturx.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "zlib"
+require "stringio"
+
+module Cpro
+  # Inspection minimale d'un PDF/A-3 Factur-X, sans dépendance à un analyseur PDF : de quoi
+  # attraper le mauvais fichier avant de le déposer, pas de quoi valider la facture.
+  module Facturx
+    ENTETE_PDF = "%PDF"
+    RACINE_CII = "CrossIndustryInvoice"
+
+    module_function
+
+    def pdf?(contenu)
+      contenu.to_s.byteslice(0, ENTETE_PDF.bytesize) == ENTETE_PDF
+    end
+
+    # Les pièces jointes d'un PDF/A-3 sont presque toujours compressées en FlateDecode : on
+    # décompresse les flux jusqu'à retrouver la racine CII. Un XML stocké sans compression
+    # échapperait à cette recherche, d'où `xml_absent?` qui ne conclut que sur le cas certain.
+    def xml(contenu)
+      octets = contenu.to_s.b
+      octets.enum_for(:scan, /stream\r?\n/).each do
+        debut = Regexp.last_match.end(0)
+        fin = octets.index("endstream", debut) || next
+        decompresse = inflate(octets[debut...fin]) || next
+        return decompresse if decompresse.include?(RACINE_CII)
+      end
+      nil
+    end
+
+    def xml?(contenu)
+      !xml(contenu).nil?
+    end
+
+    # Montant TTC déclaré par le XML embarqué (BT-112), à comparer par l'appelant à ce qu'il
+    # attend. La gem ne lit pas le PDF lisible et ne peut donc rien confronter elle-même.
+    def montant_total(contenu)
+      document = xml(contenu) or return nil
+      valeur = document[%r{<ram:GrandTotalAmount[^>]*>([^<]+)</ram:GrandTotalAmount>}, 1]
+      valeur && BigDecimal(valeur.strip)
+    rescue ArgumentError
+      nil
+    end
+
+    def inflate(flux)
+      Zlib::Inflate.inflate(flux)
+    rescue Zlib::Error
+      nil
+    end
+  end
+end

data/lib/cpro/middleware/authentication.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Middleware
+    # Injecte les deux niveaux d'authentification Chorus Pro : le jeton OAuth2 PISTE, commun à
+    # l'application, et le compte technique `cpro-account`, porté par requête via le contexte
+    # Faraday puisqu'il peut changer d'un appel à l'autre.
+    class Authentication < Faraday::Middleware
+      ACCOUNT_HEADER = "cpro-account"
+
+      def initialize(app, token_provider:)
+        super(app)
+        @token_provider = token_provider
+      end
+
+      def call(env)
+        body = env.body
+        retried = false
+
+        begin
+          reset(env, body)
+          apply(env)
+          @app.call(env)
+        rescue AuthenticationError
+          raise if retried
+
+          retried = true
+          @token_provider.invalidate!
+          retry
+        end
+      end
+
+      private
+
+      # Le corps de `env` porte la requête à l'aller et la réponse au retour : il faut le restaurer
+      # avant de rejouer l'appel, sinon la seconde tentative posterait la réponse de la première.
+      def reset(env, body)
+        env.body = body
+        env.response = nil
+        env.status = nil
+        env.response_headers = nil
+      end
+
+      def apply(env)
+        env.request_headers["Authorization"] = "Bearer #{@token_provider.token.value}"
+        account = env.request.context && env.request.context[:account]
+        env.request_headers[ACCOUNT_HEADER] = account.header_value if account
+      end
+    end
+  end
+end

data/lib/cpro/middleware/raise_error.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Middleware
+    class RaiseError < Faraday::Middleware
+      ERRORS = {
+        400 => RequestError,
+        401 => AuthenticationError,
+        403 => AuthorizationError,
+        404 => NotFoundError,
+        406 => RequestError,
+        415 => RequestError,
+        422 => RequestError,
+        429 => RateLimitError
+      }.freeze
+
+      CORRELATION_HEADER = "x-correlationid"
+
+      def on_complete(env)
+        return if env.status < 400
+
+        raise error_class(env.status).new(
+          message_for(env),
+          status: env.status,
+          body: env.body,
+          correlation_id: env.response_headers && env.response_headers[CORRELATION_HEADER]
+        )
+      end
+
+      private
+
+      def error_class(status)
+        ERRORS[status] || (status >= 500 ? ServerError : ApiError)
+      end
+
+      def message_for(env)
+        detail = detail_for(env.body) || env.reason_phrase
+        [env.status, detail].compact.join(" ")
+      end
+
+      def detail_for(body)
+        return body["message"] || body["error_description"] || body["error"] if body.is_a?(Hash)
+        return nil if body.nil?
+
+        text = body.to_s.strip
+        text.empty? ? nil : text[0, 500]
+      end
+    end
+  end
+end

data/lib/cpro/resources/annuaire.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Resources
+    class Annuaire < Base
+      TOTAL_KEY = "nombre_total_resultats"
+
+      SIRET_LENGTH = 14
+      SIREN_LENGTH = 9
+
+      # Chaque champ filtrable n'admet qu'un seul opérateur dans le swagger : l'appelant fournit
+      # `siret: "702042755"` et l'opérateur attendu est déduit d'ici.
+      OPERATEURS_SIRET = {
+        "siret" => "contient",
+        "siren" => "contient",
+        "denomination" => "contient",
+        "localite" => "contient",
+        "codePostal" => "contient",
+        "lignesAdresse" => "contient",
+        "subDivisionPays" => "contient",
+        "typeEtablissement" => "strict",
+        "etatAdministratif" => "strict"
+      }.freeze
+
+      OPERATEURS_SIREN = {
+        "siren" => "contient",
+        "raisonSociale" => "contient",
+        "typeEntite" => "strict",
+        "etatAdministratif" => "strict"
+      }.freeze
+
+      def find_by_siret(siret, **options)
+        path = "siret/code-insee:#{normalize(siret, SIRET_LENGTH, "SIRET")}"
+        Entities::Etablissement.new(get(path, query(options)))
+      end
+
+      def find_by_siren(siren, **options)
+        path = "siren/code-insee:#{normalize(siren, SIREN_LENGTH, "SIREN")}"
+        Entities::UniteLegale.new(get(path, query(options)))
+      end
+
+      # `filtres` est un mot-clé et non un positionnel : avec `search_siret(filtres, **options)`,
+      # un appel de la forme `search_siret(siren: "702042755")` verrait tous ses mots-clés partir
+      # dans `options` sous Ruby 3 et lèverait une ArgumentError.
+      def search_siret(filtres: {}, **options)
+        payload = post("siret/recherche", search_body(OPERATEURS_SIRET, filtres, options))
+        Entities::ResultatRecherche.new(payload, item_class: Entities::Etablissement, total_key: TOTAL_KEY)
+      end
+
+      def search_siren(filtres: {}, **options)
+        payload = post("siren/recherche", search_body(OPERATEURS_SIREN, filtres, options))
+        Entities::ResultatRecherche.new(payload, item_class: Entities::UniteLegale, total_key: TOTAL_KEY)
+      end
+
+      def healthcheck
+        get("healthcheck")
+      end
+
+      private
+
+      def normalize(value, length, label)
+        digits = value.to_s.gsub(/\s+/, "")
+        return digits if digits.match?(/\A\d{#{length}}\z/)
+
+        raise ArgumentError, "#{label} invalide : #{value.inspect} (#{length} chiffres attendus)"
+      end
+
+      # `champs` et `inclure` sont déclarés `explode: false` : ils voyagent en liste séparée par
+      # des virgules, et non répétés.
+      def query(options)
+        {
+          champs: join(options[:champs]),
+          inclure: join(options[:inclure]),
+          limite: options[:limite],
+          ignorer: options[:ignorer]
+        }.compact
+      end
+
+      def join(value)
+        return nil if value.nil?
+
+        Array(value).join(",")
+      end
+
+      def search_body(operateurs, filtres, options)
+        compact_body(
+          "filtres" => build_filtres(operateurs, filtres),
+          "champs" => Array(options[:champs]).map(&:to_s),
+          "inclure" => Array(options[:inclure]).map(&:to_s),
+          "tris" => build_tris(options[:tris]),
+          "limite" => options[:limite],
+          "ignorer" => options[:ignorer]
+        )
+      end
+
+      def build_filtres(operateurs, filtres)
+        (filtres || {}).each_with_object({}) do |(champ, valeur), acc|
+          key = champ.to_s
+          operateur = operateurs[key]
+          unless operateur
+            raise ArgumentError,
+                  "filtre inconnu : #{champ.inspect} (attendus : #{operateurs.keys.join(", ")})"
+          end
+
+          acc[key] = { "op" => operateur, "valeur" => valeur.to_s }
+        end
+      end
+    end
+  end
+end

data/lib/cpro/resources/base.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Resources
+    class Base
+      def initialize(client, connection)
+        @client = client
+        @connection = connection
+      end
+
+      private
+
+      attr_reader :client, :connection
+
+      def get(path, params = {})
+        request(:get, path, params: params)
+      end
+
+      def post(path, body)
+        request(:post, path, body: body)
+      end
+
+      # Le swagger Annuaire ne déclare pas cpro-account, mais l'API le rejette en 400 sans lui,
+      # healthcheck compris : toutes les ressources G2B l'exigent (vérifié en sandbox).
+      def request(method, path, params: nil, body: nil)
+        response = connection.public_send(method) do |request|
+          request.url(path, params || {})
+          request.body = body unless body.nil?
+          request.options.context = { account: required_account }
+        end
+        response.body
+      end
+
+      def required_account
+        account = client.account
+        return account if account
+
+        raise ConfigurationError,
+              "un compte technique est requis pour #{self.class.name} : " \
+              "passez-le via Cpro::Client#with_account ou Cpro::Configuration#account"
+      end
+
+      def normalize_uid(uid, label)
+        value = uid.respond_to?(:uid) ? uid.uid : uid
+        raise ArgumentError, "#{label} manquant" if value.nil? || value.to_s.empty?
+
+        value.to_s
+      end
+
+      def build_tris(tris)
+        return nil if tris.nil? || tris.empty?
+
+        tris.map { |champ, ordre| { "champ" => champ.to_s, "ordre" => ordre.to_s } }
+      end
+
+      def compact_body(body)
+        body.reject { |_, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
+      end
+    end
+  end
+end

data/lib/cpro/resources/factures.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Resources
+    class Factures < Base
+      # Contrairement à l'Annuaire, les filtres sont plats : `{"nomFlux" => "CPP004…"}` et non
+      # `{"op" => …, "valeur" => …}`. Les valeurs partent telles quelles, `codeTypeFacture` étant
+      # un entier.
+      FILTRES = %w[
+        numeroFacture dateEmissionFactureDu dateEmissionFactureAu codeTypeFacture idObjetFacture
+        siretVendeur siretAgentVendeur siretAcheteur sirenAcheteur siretTiersFacturant
+        dateStatutFactureDu dateStatutFactureAu nomFlux
+      ].freeze
+
+      TOTAL_KEY = "nombreTotalResultats"
+
+      def search(filtres:, **options)
+        payload = post("facture/recherche", search_body(filtres, options))
+        Entities::ResultatRecherche.new(payload, item_class: Entities::Facture, total_key: TOTAL_KEY)
+      end
+
+      # Cinématique documentée après un dépôt : le nomFlux rendu par `Flux#status` mène aux
+      # factures que le flux contenait.
+      def search_by_nom_flux(nom_flux, **options)
+        search(filtres: { nomFlux: nom_flux.respond_to?(:nom_flux) ? nom_flux.nom_flux : nom_flux }, **options)
+      end
+
+      def find(uid)
+        payload = get("facture/#{normalize_uid(uid, "identifiant de facture")}")
+        payload = {} unless payload.is_a?(Hash)
+
+        Entities::Facture.new(payload["facture"], historique: payload["historique"])
+      end
+
+      def healthcheck
+        get("healthcheck")
+      end
+
+      private
+
+      def search_body(filtres, options)
+        compact_body(
+          "filtres" => build_filtres(filtres),
+          "champs" => Array(options[:champs]).map(&:to_s),
+          "tris" => build_tris(options[:tris]),
+          "limite" => options[:limite],
+          "ignorer" => options[:ignorer]
+        )
+      end
+
+      def build_filtres(filtres)
+        raise ArgumentError, "au moins un filtre est requis" if filtres.nil? || filtres.empty?
+
+        filtres.each_with_object({}) do |(champ, valeur), acc|
+          key = champ.to_s
+          unless FILTRES.include?(key)
+            raise ArgumentError, "filtre inconnu : #{champ.inspect} (attendus : #{FILTRES.join(", ")})"
+          end
+
+          acc[key] = valeur
+        end
+      end
+    end
+  end
+end

data/lib/cpro/resources/flux.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Cpro
+  module Resources
+    class Flux < Base
+      def deposit_facturx(source, name: nil)
+        depot(source, :facturx, name: name) { |contenu| verifier_facturx(contenu) }
+      end
+
+      def deposit_ubl(source, name: nil)
+        depot(source, :ubl, name: name)
+      end
+
+      # Émettre un statut de cycle de vie : le fichier attendu est un CDAR D22B conforme à
+      # l'Annexe A de la norme AFNOR XP Z12-012. La gem le transporte, elle ne le fabrique pas.
+      def deposit_cdv(source, name: nil)
+        depot(source, :cdv, name: name)
+      end
+
+      def deposit_ereporting(source, name: nil)
+        depot(source, :ereporting, name: name)
+      end
+
+      def emettre_statut(facture, statut, **options)
+        message = Cdv::Message.new(facture: facture, statut: statut, **options)
+        depot(StringIO.new(message.to_xml), :cdv, name: message.nom_fichier)
+      end
+
+      def status(uid)
+        status!(uid)
+      rescue NotFoundError
+        nil
+      end
+
+      def status!(uid)
+        Entities::StatutFlux.new(get("flux/#{normalize_uid(uid, "identifiant de flux")}"))
+      end
+
+      def healthcheck
+        get("healthcheck")
+      end
+
+      private
+
+      def depot(source, code_interface, name:)
+        enveloppe = Enveloppe.from(source, code_interface: code_interface, name: name)
+        yield enveloppe.content if block_given?
+        Entities::DepotFlux.new(post("flux", enveloppe.payload))
+      end
+
+      def verifier_facturx(contenu)
+        raise ArgumentError, "le fichier déposé n'est pas un PDF" unless Facturx.pdf?(contenu)
+        return if Facturx.xml?(contenu)
+
+        raise ArgumentError, "aucun XML Factur-X n'a été trouvé dans le PDF : vérifiez qu'il " \
+                             "s'agit bien d'un PDF/A-3 avec sa pièce jointe factur-x.xml"
+      end
+    end
+  end
+end

data/lib/cpro/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cpro
+  VERSION = "0.1.0"
+end

data/lib/cpro-client.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "cpro"

data/lib/cpro.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+require_relative "cpro/version"
+require_relative "cpro/errors"
+require_relative "cpro/configuration"
+require_relative "cpro/account"
+require_relative "cpro/auth/token"
+require_relative "cpro/auth/token_provider"
+require_relative "cpro/middleware/authentication"
+require_relative "cpro/middleware/raise_error"
+require_relative "cpro/connection"
+require_relative "cpro/entities/base"
+require_relative "cpro/entities/ligne_annuaire"
+require_relative "cpro/entities/lignes_annuaire"
+require_relative "cpro/entities/unite_legale"
+require_relative "cpro/entities/etablissement"
+require_relative "cpro/entities/note_statut"
+require_relative "cpro/entities/motif_rejet"
+require_relative "cpro/entities/changement_statut"
+require_relative "cpro/entities/facture"
+require_relative "cpro/entities/resultat_recherche"
+require_relative "cpro/entities/depot_flux"
+require_relative "cpro/entities/statut_flux"
+require_relative "cpro/cdv/statut"
+require_relative "cpro/cdv/message"
+require_relative "cpro/facturx"
+require_relative "cpro/archive"
+require_relative "cpro/enveloppe"
+require_relative "cpro/resources/base"
+require_relative "cpro/resources/annuaire"
+require_relative "cpro/resources/flux"
+require_relative "cpro/resources/factures"
+require_relative "cpro/client"
+
+module Cpro
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      configuration
+    end
+
+    def client(**options)
+      Client.new(configuration, **options)
+    end
+
+    def reset!
+      @configuration = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: cpro-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Hôtentic
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-08-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: 'Client Ruby des API G2B de Chorus Pro (PPF) : authentification OAuth2
+  PISTE, consultation de l''annuaire par SIRET ou SIREN, et dépôt de factures Factur-X.'
+email:
+- contact@hotentic.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- cpro-client.gemspec
+- lib/cpro-client.rb
+- lib/cpro.rb
+- lib/cpro/account.rb
+- lib/cpro/archive.rb
+- lib/cpro/auth/token.rb
+- lib/cpro/auth/token_provider.rb
+- lib/cpro/cdv/message.rb
+- lib/cpro/cdv/statut.rb
+- lib/cpro/client.rb
+- lib/cpro/configuration.rb
+- lib/cpro/connection.rb
+- lib/cpro/entities/base.rb
+- lib/cpro/entities/changement_statut.rb
+- lib/cpro/entities/depot_flux.rb
+- lib/cpro/entities/etablissement.rb
+- lib/cpro/entities/facture.rb
+- lib/cpro/entities/ligne_annuaire.rb
+- lib/cpro/entities/lignes_annuaire.rb
+- lib/cpro/entities/motif_rejet.rb
+- lib/cpro/entities/note_statut.rb
+- lib/cpro/entities/resultat_recherche.rb
+- lib/cpro/entities/statut_flux.rb
+- lib/cpro/entities/unite_legale.rb
+- lib/cpro/enveloppe.rb
+- lib/cpro/errors.rb
+- lib/cpro/facturx.rb
+- lib/cpro/middleware/authentication.rb
+- lib/cpro/middleware/raise_error.rb
+- lib/cpro/resources/annuaire.rb
+- lib/cpro/resources/base.rb
+- lib/cpro/resources/factures.rb
+- lib/cpro/resources/flux.rb
+- lib/cpro/version.rb
+homepage: https://hotentic.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://hotentic.com
+  source_code_uri: https://github.com/hotentic/cpro-client
+  changelog_uri: https://github.com/hotentic/cpro-client/releases
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key:
+specification_version: 4
+summary: A ruby client for the Chorus Pro API
+test_files: []