cpro-client 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: eed2218b6135210909bb231938a2adf3d8f9b432a19468576b232ffd2f352d7a
-  data.tar.gz: 95739510c05be2fdc248b2f001e4b53e08b3487162dbb29f50bc26606d929e06
+  metadata.gz: fcf97fbee94114c1241fb76a3b3ec620dd7d8c2e40435bebfe146ce7b65a3e92
+  data.tar.gz: 0b3e4f80fe36110c60a46d7adc951cb0bd662093a30e39a0f19fb9e4c252096d
 SHA512:
-  metadata.gz: 7208819c95be0220d40498c3d09c5df5479619c652c6103aac41903ce1cac6054f47b53a7c87638fd7b474e99581a61b6924ab1d0f17b633bb18a72d431e8a94
-  data.tar.gz: 4c292e8c13863bdff0fe54ab567e42880c4d25e5d928ca70fb6c1a83284198912cc14b5dd787f0733763e181a7923f08ab7768a0ee5007b5b4e52b3719c4b7f0
+  metadata.gz: 4f010893e86d5f3dec2742aca27ea56606f6facb294c23cc613f91073d4ebf3b3f56dc1fdea650121b76a706680a65bd4921c875230a0e00beb428d4306f7876
+  data.tar.gz: 65724ca9625aa0328e6d3b14f10005f087614e589587f73e706b17d515b1091f3633f960bf9036a8031e30abdab360814856d076de551eaa0f5a860759b3a0a9

data/CHANGELOG.md

@@ -1,6 +1,30 @@
 ## [Unreleased]
 
 
+## [0.2.5] - 2026-09-05
+
+### Ajouté
+- `Cpro::Client#suivi` enchaîne les appels de suivi d'un dépôt — statut du flux, recherche de la
+  facture, consultation avec son historique — et rend un `Cpro::Suivi` qui nomme l'étape atteinte :
+  `:flux_en_attente` (404 du PPF, cas nominal juste après un dépôt), `:flux_irrecevable`,
+  `:facture_introuvable` (204, ambigu par nature) ou `:facture_connue`. Il court-circuite dès
+  qu'un palier interdit d'aller plus loin : un appel tant que le flux n'est pas traité, trois au
+  plus. Il n'attend jamais — la cadence d'interrogation appartient à l'appelant — et laisse
+  `statut_flux` et `facture` accessibles pour ce qu'il n'interprète pas.
+- `Cpro::Entities::Facture#dernier_incident`, relayé par `Cpro::Suivi#dernier_incident`, isole le
+  dernier changement de statut porteur de motifs — l'incident en cours — là où `motifs_rejet`
+  cumule tout l'historique. Il rend le changement et non le motif : un même changement en porte
+  plusieurs, une facture « Déposée » pouvant cumuler `NON_TRANSMISE` et `REJ_UNI`.
+- `Cpro::Suivi#motifs` rassemble les motifs de rejet, qu'ils viennent du flux ou de l'historique de
+  la facture : l'appelant n'a plus à savoir où le dépôt s'est arrêté pour aller les chercher.
+- `Cpro::Entities::Facture#en_echec?` — vrai dès qu'une facture demande une intervention, que son
+  statut l'annonce ou non. Chorus Pro accroche ses motifs de rejet au statut porteur, qui peut
+  être anodin : une facture « Déposée » assortie de `NON_TRANSMISE` ne parviendra pas à son
+  destinataire alors que `rejetee?` répond faux. Le prédicat couvre les statuts `REJETEE` et
+  `ERREUR_ROUTAGE` ainsi que tout motif présent dans l'historique — lequel n'est renseigné que
+  par `Factures#find`.
+
+
 ## [0.2.3] - 2026-08-31
 
 ### Ajouté

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cpro-client (0.2.4)
+    cpro-client (0.2.5)
       faraday (>= 0.9, < 3.0)
 
 GEM

data/README.md

@@ -254,6 +254,48 @@ aucune facture ne correspond que lorsque le compte technique n'est rattaché ni
 callback, et les statuts des factures G2B ne sont pas consultables sur le portail Chorus Pro : le
 suivi passe nécessairement par une interrogation périodique de cette API.
 
+## Suivre un dépôt en un appel
+
+Les quatre étapes du suivi — statut du flux, recherche par `nomFlux`, consultation, lecture des
+motifs — se réduisent à une méthode, qui nomme l'étape atteinte plutôt que de lever ou de rendre
+`nil` :
+
+```ruby
+suivi = client.suivi(depot)
+
+suivi.etape        # :flux_en_attente, :flux_irrecevable, :facture_introuvable, :facture_connue
+suivi.en_echec?    # au niveau de l'enveloppe comme à celui de la facture
+suivi.motifs       # les motifs, d'où qu'ils viennent
+suivi.facture      # la facture et son historique, à l'étape :facture_connue
+suivi.statut_flux  # le statut brut du flux, dès qu'il est connu
+```
+
+`motifs` cumule tout l'historique — un incident réglé y côtoie l'incident courant. Pour n'avoir que
+le plus récent, avec le statut qui le portait et sa date :
+
+```ruby
+incident = suivi.dernier_incident      # un ChangementStatut, ou nil
+
+incident.statut                        # "DEPOSEE"
+incident.date                          # 2026-09-04 19:18:31 UTC
+incident.motifs_rejet.map(&:code)      # ["NON_TRANSMISE", "REJ_UNI"]
+```
+
+Il rend le changement et non le motif : un même changement en porte plusieurs, et n'en exposer
+qu'un les masquerait. Il vaut `nil` à l'étape `:flux_irrecevable`, où il n'y a pas encore de
+facture — `motifs` reste alors l'accès uniforme.
+
+| Étape | Ce qui s'est passé | Appels | Suite |
+| --- | --- | :-: | --- |
+| `:flux_en_attente` | 404 sur le flux — cas nominal | 1 | réinterroger |
+| `:flux_irrecevable` | enveloppe refusée, motifs sur le flux | 1 | terminal |
+| `:facture_introuvable` | flux recevable, recherche vide | 2 | réinterroger, puis vérifier le rattachement du compte |
+| `:facture_connue` | facture et historique disponibles | 3 | lire `en_echec?` et les motifs |
+
+La méthode **n'attend pas** : c'est une photographie, la cadence d'interrogation reste à l'appelant.
+Seuls le 404 du flux et la recherche vide deviennent des étapes ; un 401, un 403 ou un 5xx
+continuent de lever.
+
 ## Servir plusieurs entités
 
 L'AIFE distingue trois types de raccordement API. Celui qui s'applique détermine le modèle à

data/lib/cpro/client.rb

@@ -19,6 +19,12 @@ module Cpro
       self.class.new(configuration, account: account, token_provider: token_provider, connections: connections)
     end
 
+    # Enchaîne les appels de suivi d'un dépôt et rend une synthèse. Traverse deux ressources,
+    # d'où sa place ici plutôt que sur l'une d'elles.
+    def suivi(depot)
+      Suivi.pour(self, depot)
+    end
+
     def annuaire
       @annuaire ||= Resources::Annuaire.new(self, connection_for(ANNUAIRE_PATH))
     end

data/lib/cpro/entities/facture.rb

@@ -10,6 +10,11 @@ module Cpro
         CHANGEMENT_DE_COMPTE_A_PAYER NON_AFFACTUREE AFFACTUREE AFFACTUREE_CONFIDENTIEL
       ].freeze
 
+      EPOQUE = Time.at(0).utc
+
+      # Statuts qui constatent par eux-mêmes qu'une facture n'arrivera pas.
+      STATUTS_EN_ECHEC = %w[REJETEE ERREUR_ROUTAGE].freeze
+
       CHAMPS = {
         uid: "uidFacture",
         numero: "numeroFacture",
@@ -77,6 +82,36 @@ module Cpro
         historique.flat_map(&:motifs_rejet)
       end
 
+      # Le dernier changement de statut porteur de motifs — celui qui décrit l'incident en cours,
+      # là où `motifs_rejet` cumule tout l'historique, motifs devenus caducs compris.
+      #
+      # Rend le changement et non le motif : un même changement en porte plusieurs — une facture
+      # « Déposée » peut cumuler NON_TRANSMISE et REJ_UNI — et n'en exposer qu'un les masquerait.
+      # Le rang départage deux changements de même date, le plus récent l'emportant.
+      def dernier_incident
+        incidents = historique.select(&:rejet?)
+        incidents.each_with_index.max_by { |changement, rang| [changement.date || EPOQUE, rang] }&.first
+      end
+
+      # Vrai dès qu'une facture demande une intervention, que son statut l'annonce ou non : un
+      # motif de rejet peut être porté par un statut anodin. Une facture « Déposée » accompagnée
+      # de NON_TRANSMISE en est le cas type — `rejetee?` répond faux, et pourtant le destinataire
+      # ne la recevra pas par la plateforme.
+      #
+      # Attention au mot « échec » : NON_TRANSMISE n'invalide pas la facture. Le dossier de
+      # spécifications externes est explicite — ce statut « permet à l'entité publique de
+      # justifier qu'elle a bien émis une facture électronique et qu'elle a donc respecté ses
+      # obligations réglementaires ». Il n'y a donc rien à redéposer ; il y a à livrer autrement.
+      #
+      # Le refus de l'acheteur (REFUSEE) n'en fait pas partie : c'est une décision métier, une
+      # étape normale du cycle de vie, pas un incident. Elle se lit par `refusee?`.
+      #
+      # L'historique n'étant renseigné que par `Factures#find`, une facture issue d'une recherche
+      # ne peut être jugée que sur son statut.
+      def en_echec?
+        STATUTS_EN_ECHEC.include?(statut) || historique.any?(&:rejet?)
+      end
+
       def to_s
         [numero, statut].compact.join(" ")
       end

data/lib/cpro/version.rb

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

data/lib/cpro.rb

@@ -35,6 +35,7 @@ require_relative "cpro/resources/base"
 require_relative "cpro/resources/annuaire"
 require_relative "cpro/resources/flux"
 require_relative "cpro/resources/factures"
+require_relative "cpro/suivi"
 require_relative "cpro/client"
 
 module Cpro

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cpro-client
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - Hôtentic
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-04 00:00:00.000000000 Z
+date: 2026-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday