pennylane-client 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a12edf1a99b16ac791ed08bab5a859674832996f5e272f04291dcd662f687a85
-  data.tar.gz: 7c3f8372674c76c721500494a96dab63b95feae0a405a13674f5c14280f8e4fb
+  metadata.gz: 94653df77c6a2fc7f58347338d0591fe5af9fb27567d55a50fddb4249b4f5bd9
+  data.tar.gz: e55bfa20edd8f782e88b95a4409e8a18ab13ee90eaeac9da94a7c3a275b4cb3b
 SHA512:
-  metadata.gz: 874a9901d154747bf9bb0b2c4b4e155ca63f8d0f7336801802dc41ac712d1ccd81f8b392cba67f67ad22a674ccc54fe1de7eef7a6f5324016b9a094c418d7d69
-  data.tar.gz: bf570896b3893262744a3db6b8bce9b7beba5db8ac69c567a2ec2c4cd74232b8b66fc24c22d0da68a2b8f06a62d01c5097a9aa5e0dda76b0eff351778c765a61
+  metadata.gz: f385797cce13228dd684878e630b746fa2e5e2baf30bcc56ff88bdc63bb2c74c4e22fc5aa863abbd08c4a49cf5f8c4ee14ebcaf8309a89a5ec741c2b20bf9cc1
+  data.tar.gz: 217e0c3ee07cf1f95afe8a8110bd81639eeb38a7a80aca2dfbd6ad01458c6218fef9954fd93f84be3c0509c170a0fcd5e40417e4fc96b565e61931359e5820f7

data/CHANGELOG.md

@@ -1,5 +1,20 @@
 ## [Unreleased]
 
+
+## 0.2.0
+
+### Ajouté
+- `Customers#find_or_create_by` retrouve une entreprise par son SIREN ou son SIRET, et la crée
+  sinon.
+
+### Modifié
+- `CustomerInvoices#import` : `customer_id` devient facultatif. Sans lui, la facture est déposée sans
+  `invoice_options`, et Pennylane décide seul de son rattachement à un client.
+- `Customers#find_by_reg_no` rend le plus ancien client quand plusieurs portent le même `reg_no`.
+
+
+## 0.1.0
+
 ### Ajouté
 - `Pennylane.client(token:)` : un client par token, donc par société Pennylane.
 - `CustomerInvoices#import` dépose une facture Factur-X, rattachée au client `customer_id`. Un

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pennylane-client (0.1.0)
+    pennylane-client (0.2.0)
       faraday (>= 0.9, < 3.0)
 
 GEM

data/README.md

@@ -43,28 +43,45 @@ rejouée après le délai annoncé par l'API, `rate_limit_retries` fois au plus.
 
 ## Clients
 
-Une facture se dépose au nom d'un client Pennylane. La référence externe, unique dans une société,
-fait le lien avec le client de l'application hôte :
+Une facture se dépose au nom d'un client Pennylane. Une entreprise se retrouve par son SIREN ou son
+SIRET, et se crée si elle manque :
 
 ```ruby
-customer = client.customers.find_by_external_reference("client-812") ||
+customer = client.customers.find_or_create_by(
+  "81234567600009", # SIRET ou SIREN
+  name: "SARL COTEAUX ET COMPAGNIE",
+  vat_number: "FR19812345676",
+  billing_address: { address: "123 avenue des Alpages", postal_code: "74000", city: "Annecy",
+                     country_alpha2: "FR" }
+)
+```
+
+Les attributs ne servent qu'à la création, mais ils sont vérifiés à chaque appel, avant toute
+requête. Un SIRET est ramené à son SIREN, que porte le client créé en `reg_no` ; la recherche essaie
+les deux formes. Si plusieurs clients ont le même SIREN, le plus ancien est rendu. La recherche
+suivie de la création n'est pas atomique : deux appels simultanés pour une entreprise absente
+peuvent la créer deux fois.
+
+Un particulier n'a pas de SIREN. Il se crée avec `create`, et se retrouve par la référence externe,
+unique dans une société, qui fait le lien avec le client de l'application hôte :
+
+```ruby
+customer = client.customers.find_by_external_reference("client-813") ||
            client.customers.create(
-             customer_type: :company,
-             name: "SARL COTEAUX ET COMPAGNIE",
-             reg_no: "812345676",
-             vat_number: "FR19812345676",
-             billing_address: { address: "123 avenue des Alpages", postal_code: "74000", city: "Annecy",
+             customer_type: :individual,
+             first_name: "Jean",
+             last_name: "Dupont",
+             billing_address: { address: "3 rue Victor Hugo", postal_code: "69002", city: "Lyon",
                                 country_alpha2: "FR" },
-             external_reference: "client-812"
+             external_reference: "client-813"
            )
 ```
 
-Un client `individual` prend `first_name` et `last_name` au lieu de `name`, et n'a ni `reg_no` ni
-`vat_number`. Les attributs sont vérifiés avant l'appel : l'API refuse un attribut inconnu ou
+`create` vérifie lui aussi les attributs avant l'appel : l'API refuse un attribut inconnu ou
 manquant sans dire lequel. Une référence externe déjà prise lève une `Pennylane::RequestError`
 (422).
 
-`find_by_reg_no` retrouve un client par son SIREN ; `find`, `list` et `all` fonctionnent comme pour
+`find_by_reg_no` retrouve un client par son `reg_no` exact ; `find`, `list` et `all` fonctionnent comme pour
 les factures, avec les filtres `id`, `customer_type`, `ledger_account_id`, `name`,
 `external_reference`, `reg_no` et `emails`, et un tri sur `id`.
 
@@ -84,8 +101,10 @@ rescue Pennylane::DuplicateInvoiceError => e
 end
 ```
 
-`import` accepte un chemin ou un IO ; un IO sans chemin demande `filename:`. `customer_id` est
-l'identifiant du client dans Pennylane.
+`import` accepte un chemin ou un IO ; un IO sans chemin demande `filename:`. `customer_id`,
+facultatif, rattache la facture à un client Pennylane ; Pennylane le reprend une fois le fichier lu.
+Sans lui, Pennylane décide seul du rattachement, d'après le Factur-X — un cas pas encore mesuré en
+sandbox.
 
 Pennylane refuse un fichier déjà déposé et donne l'identifiant de la facture existante : un dépôt
 interrompu avant sa réponse peut donc être rejoué sans risque. Mais il ne reconnaît le doublon qu'au

data/lib/pennylane/client.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pennylane
+  class Client
+    attr_reader :configuration
+
+    def initialize(token:, configuration: Pennylane.configuration)
+      raise ConfigurationError, "un token d'API Pennylane est requis" if token.nil? || token.to_s.strip.empty?
+
+      @token = token.to_s
+      @configuration = configuration
+    end
+
+    def customer_invoices
+      @customer_invoices ||= Resources::CustomerInvoices.new(connection)
+    end
+
+    def customers
+      @customers ||= Resources::Customers.new(connection)
+    end
+
+    def inspect
+      "#<#{self.class.name} token=[FILTERED]>"
+    end
+
+    private
+
+    def connection
+      @connection ||= Connection.build(configuration, @token)
+    end
+  end
+end

data/lib/pennylane/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pennylane
+  class Configuration
+    DEFAULT_BASE_URL = "https://app.pennylane.com/api/external/v2"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+    DEFAULT_RATE_LIMIT_RETRIES = 2
+
+    attr_accessor :base_url, :timeout, :open_timeout, :adapter, :rate_limit_retries
+
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @rate_limit_retries = DEFAULT_RATE_LIMIT_RETRIES
+      @adapter = Faraday.default_adapter
+    end
+  end
+end

data/lib/pennylane/connection.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Connection
+    # Middlewares ordering matters here
+    def self.build(configuration, token)
+      Faraday.new(url: "#{configuration.base_url}/", headers: { "Authorization" => "Bearer #{token}" }) do |faraday|
+        faraday.use Middleware::EncodeJson
+        faraday.use Middleware::RateLimit, retries: configuration.rate_limit_retries
+        faraday.use Middleware::RaiseError
+        faraday.use Middleware::ParseJson
+        faraday.options.timeout = configuration.timeout
+        faraday.options.open_timeout = configuration.open_timeout
+        faraday.adapter configuration.adapter
+      end
+    end
+  end
+end

data/lib/pennylane/entities/base.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "time"
+
+module Pennylane
+  module Entities
+    class Base
+      class << self
+        private
+
+        def fields(*names)
+          names.each { |name| define_method(name) { payload[name.to_s] } }
+        end
+
+        # Les montants arrivent en chaînes décimales : BigDecimal les garde exacts.
+        def amounts(*names)
+          names.each { |name| define_method(name) { parse_amount(payload[name.to_s]) } }
+        end
+
+        def dates(*names)
+          names.each { |name| define_method(name) { parse_date(payload[name.to_s]) } }
+        end
+
+        def times(*names)
+          names.each { |name| define_method(name) { parse_time(payload[name.to_s]) } }
+        end
+      end
+
+      attr_reader :payload
+
+      def initialize(payload = nil)
+        @payload = payload.is_a?(Hash) ? payload : {}
+      end
+
+      def to_h
+        payload
+      end
+
+      def ==(other)
+        other.instance_of?(self.class) && other.payload == payload
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, payload].hash
+      end
+
+      private
+
+      def dig_payload(*keys)
+        keys.reduce(payload) { |value, key| value.is_a?(Hash) ? value[key] : nil }
+      end
+
+      def parse_amount(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        BigDecimal(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def parse_date(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        Date.iso8601(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+
+      def parse_time(value)
+        return nil if value.nil? || value.to_s.empty?
+
+        Time.iso8601(value.to_s)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/pennylane/entities/change.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Entities
+    class Change < Base
+      OPERATIONS = %w[insert update delete].freeze
+
+      fields :id, :operation
+      times :processed_at, :created_at, :updated_at
+
+      OPERATIONS.each do |value|
+        define_method(:"#{value}?") { operation == value }
+      end
+    end
+  end
+end

data/lib/pennylane/entities/customer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Entities
+    class Customer < Base
+      fields :id, :customer_type, :name, :first_name, :last_name, :reg_no, :vat_number, :external_reference,
+             :emails, :phone, :recipient, :reference, :notes, :payment_conditions, :billing_iban, :billing_language,
+             :billing_address, :delivery_address, :electronic_billing_address
+      times :created_at, :updated_at
+
+      def company?
+        customer_type == "company"
+      end
+
+      def individual?
+        customer_type == "individual"
+      end
+
+      def ledger_account_id
+        dig_payload("ledger_account", "id")
+      end
+
+      def to_s
+        name || [first_name, last_name].compact.join(" ")
+      end
+    end
+  end
+end

data/lib/pennylane/entities/customer_invoice.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Entities
+    class CustomerInvoice < Base
+      STATUSES = %w[
+        archived incomplete cancelled paid partially_paid partially_cancelled upcoming late draft
+        credit_note proforma shipping_order purchasing_order estimate_pending estimate_accepted
+        estimate_invoiced estimate_denied
+      ].freeze
+
+      E_INVOICING_STATUSES = %w[
+        submitted sent accepted approved refused rejected in_dispute partially_collected collected
+      ].freeze
+
+      fields :id, :invoice_number, :label, :currency, :status, :external_reference, :filename, :public_file_url,
+             :schematron_validation_status
+      amounts :amount, :currency_amount, :currency_amount_before_tax, :currency_tax, :tax,
+              :remaining_amount_with_tax, :remaining_amount_without_tax
+      dates :date, :deadline
+      times :created_at, :updated_at, :archived_at
+
+      # `paid?` et `draft?` lisent les champs booléens du même nom, pas le statut.
+      (STATUSES - %w[paid draft]).each do |value|
+        define_method(:"#{value}?") { status == value }
+      end
+
+      def paid?
+        payload["paid"] == true
+      end
+
+      def draft?
+        payload["draft"] == true
+      end
+
+      def factur_x?
+        payload["factur_x"] == true
+      end
+
+      def customer_id
+        dig_payload("customer", "id")
+      end
+
+      def e_invoicing_status
+        dig_payload("e_invoicing", "status")
+      end
+
+      def e_invoicing_reason
+        dig_payload("e_invoicing", "reason")
+      end
+
+      def to_s
+        [invoice_number, status].compact.join(" ")
+      end
+    end
+  end
+end

data/lib/pennylane/entities/e_invoice_import.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Entities
+    class EInvoiceImport < Base
+      fields :id, :url
+    end
+  end
+end

data/lib/pennylane/entities/matched_transaction.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Entities
+    # Transaction bancaire rapprochée de la facture. Ses montants sont ceux de la transaction
+    # entière, qui peut solder plusieurs factures : la part affectée à une facture se lit dans
+    # son `remaining_amount_with_tax`.
+    class MatchedTransaction < Base
+      fields :id, :label, :currency
+      amounts :amount, :currency_amount, :fee, :currency_fee, :outstanding_balance
+      dates :date
+      times :created_at, :updated_at, :archived_at
+    end
+  end
+end

data/lib/pennylane/entities/page.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Entities
+    class Page < Base
+      include Enumerable
+
+      attr_reader :item_class
+
+      def initialize(payload, item_class:)
+        super(payload)
+        @item_class = item_class
+      end
+
+      def items
+        @items ||= Array(payload["items"]).map { |item| item_class.new(item) }
+      end
+
+      def each(&block)
+        items.each(&block)
+      end
+
+      def more?
+        payload["has_more"] == true
+      end
+
+      def next_cursor
+        payload["next_cursor"]
+      end
+
+      def size
+        items.size
+      end
+      alias length size
+
+      def empty?
+        items.empty?
+      end
+
+      def ==(other)
+        super && other.item_class == item_class
+      end
+      alias eql? ==
+    end
+  end
+end

data/lib/pennylane/entities/payment.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Entities
+    # Paiement passé par un moyen de paiement Pennylane (Qonto, lien de paiement, GoCardless,
+    # Stripe). Un virement reçu hors de Pennylane apparaît en MatchedTransaction.
+    class Payment < Base
+      fields :id, :label, :currency, :status
+      amounts :currency_amount
+      times :created_at, :updated_at
+    end
+  end
+end

data/lib/pennylane/entities/settlement.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Entities
+    # Règlement d'une facture : ce qui en a été encaissé, et par quels paiements.
+    #
+    # Le montant encaissé se lit dans le reste à payer, que Pennylane tient à jour à chaque
+    # rapprochement bancaire. Le détail vient des transactions rapprochées, dont chacune porte le
+    # montant de la transaction entière : leur somme n'égale le montant encaissé que si aucune n'est
+    # partagée avec une autre facture, d'où `consistent?`.
+    class Settlement
+      attr_reader :invoice, :payments
+
+      def initialize(invoice, transactions)
+        @invoice = invoice
+        @payments = transactions.sort_by { |transaction| [transaction.date || Date.new(0), transaction.id.to_i] }
+      end
+
+      def paid?
+        invoice.paid?
+      end
+
+      def total
+        invoice.currency_amount
+      end
+
+      def remaining_amount
+        invoice.remaining_amount_with_tax
+      end
+
+      def settled_amount
+        total - remaining_amount if total && remaining_amount
+      end
+
+      def payments_amount
+        payments.sum(BigDecimal("0")) { |payment| payment.currency_amount || BigDecimal("0") }
+      end
+
+      def consistent?
+        !settled_amount.nil? && payments_amount == settled_amount
+      end
+
+      # « Marquer comme payée » lève le drapeau `paid` sans toucher au reste à payer ni enregistrer
+      # de paiement : la facture se dit payée alors qu'un reliquat n'est couvert par aucun encaissement.
+      def marked_paid?
+        paid? && !remaining_amount.nil? && remaining_amount.positive?
+      end
+    end
+  end
+end

data/lib/pennylane/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Pennylane
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class ApiError < Error
+    attr_reader :status, :body
+
+    def initialize(message, status: nil, body: nil)
+      @status = status
+      @body = body
+      super(message)
+    end
+
+    # Renseignés sur les erreurs de validation des paramètres seulement, de la forme
+    # `{"message", "code", "field", "payload"}` ; les autres erreurs ont la forme `{"status", "error"}`.
+    def code
+      body["code"] if body.is_a?(Hash)
+    end
+
+    def field
+      body["field"] if body.is_a?(Hash)
+    end
+  end
+
+  class RequestError < ApiError; end
+  class AuthenticationError < ApiError; end
+  class AuthorizationError < ApiError; end
+  class NotFoundError < ApiError; end
+  class ConflictError < ApiError; end
+  class ServerError < ApiError; end
+
+  # Pennylane refuse de réimporter un fichier identique à celui d'une facture existante, dont il
+  # donne l'identifiant.
+  class DuplicateInvoiceError < ConflictError
+    attr_reader :invoice_id
+
+    def initialize(message, invoice_id: nil, **options)
+      @invoice_id = invoice_id
+      super(message, **options)
+    end
+  end
+
+  class RateLimitError < ApiError
+    attr_reader :retry_after
+
+    def initialize(message, retry_after: nil, **options)
+      @retry_after = retry_after
+      super(message, **options)
+    end
+  end
+end

data/lib/pennylane/filter.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "date"
+require "json"
+
+module Pennylane
+  # Traduit `{ invoice_number: "F-1", id: { in: [1, 2] } }` en paramètre `filter` de l'API. Une
+  # valeur nue vaut `eq`.
+  class Filter
+    COMPARISON = %w[lt lteq gt gteq eq not_eq in not_in].freeze
+    INCLUSION = %w[eq not_eq in not_in].freeze
+
+    def initialize(operators_by_field)
+      @operators_by_field = operators_by_field
+    end
+
+    def to_param(filters)
+      return nil if filters.nil? || filters.empty?
+
+      JSON.generate(filters.flat_map { |field, condition| conditions(field.to_s, condition) })
+    end
+
+    private
+
+    def conditions(field, condition)
+      operators = @operators_by_field.fetch(field) do
+        raise ArgumentError, "filtre inconnu : #{field.inspect} (attendus : #{@operators_by_field.keys.join(", ")})"
+      end
+      condition = { eq: condition } unless condition.is_a?(Hash)
+
+      condition.map do |operator, value|
+        unless operators.include?(operator.to_s)
+          raise ArgumentError,
+                "opérateur #{operator.to_s.inspect} refusé sur #{field.inspect} (attendus : #{operators.join(", ")})"
+        end
+
+        { "field" => field, "operator" => operator.to_s, "value" => serialize(value) }
+      end
+    end
+
+    # Mesuré en sandbox : un booléen JSON est refusé, avec un message trompeur (« Value "true" is
+    # not allowed… Allowed values are "true, false" ») ; seule sa forme textuelle passe.
+    def serialize(value)
+      case value
+      when Array then value.map { |item| serialize(item) }
+      when true, false then value.to_s
+      when Date, Time then value.iso8601
+      else value
+      end
+    end
+  end
+end

data/lib/pennylane/middleware/encode_json.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pennylane
+  module Middleware
+    # Faraday n'embarque de middleware JSON qu'à partir de la 1.0. Un corps déjà sérialisé, comme
+    # celui d'un envoi multipart, passe tel quel.
+    class EncodeJson < Faraday::Middleware
+      CONTENT_TYPE = "Content-Type"
+      MIME = "application/json"
+
+      def call(env)
+        encode(env) unless env.body.nil? || env.body.is_a?(String)
+        @app.call(env)
+      end
+
+      private
+
+      def encode(env)
+        env.request_headers[CONTENT_TYPE] ||= MIME
+        env.body = JSON.generate(env.body)
+      end
+    end
+  end
+end

data/lib/pennylane/middleware/parse_json.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pennylane
+  module Middleware
+    # Faraday n'embarque de middleware JSON qu'à partir de la 1.0.
+    class ParseJson < Faraday::Middleware
+      CONTENT_TYPE = /\bjson\z/.freeze
+
+      def call(env)
+        @app.call(env).on_complete { |response| response.body = parse(response) }
+      end
+
+      private
+
+      def parse(env)
+        body = env.body
+        return body unless json?(env) && body.is_a?(String) && !body.strip.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body
+      end
+
+      def json?(env)
+        type = env.response_headers && env.response_headers["content-type"]
+        type.to_s.split(";").first.to_s.strip.match?(CONTENT_TYPE)
+      end
+    end
+  end
+end

data/lib/pennylane/middleware/raise_error.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Middleware
+    class RaiseError < Faraday::Middleware
+      ERRORS = {
+        400 => RequestError,
+        401 => AuthenticationError,
+        403 => AuthorizationError,
+        404 => NotFoundError,
+        409 => ConflictError,
+        422 => RequestError,
+        429 => RateLimitError
+      }.freeze
+
+      RETRY_AFTER_HEADER = "retry-after"
+
+      # Appelé sur l'objet réponse : `on_complete` n'existe pas sur Faraday::Middleware avant la 1.0.
+      def call(env)
+        @app.call(env).on_complete { |response| check(response) }
+      end
+
+      private
+
+      def check(env)
+        return if env.status < 400
+
+        error_class = ERRORS[env.status] || (env.status >= 500 ? ServerError : ApiError)
+        options = { status: env.status, body: env.body }
+        options[:retry_after] = retry_after(env) if error_class == RateLimitError
+        raise error_class.new(message_for(env), **options)
+      end
+
+      def message_for(env)
+        detail = detail_for(env.body)
+        detail ||= env.reason_phrase if env.respond_to?(:reason_phrase)
+        [env.status, detail, request_label(env)].compact.join(" ")
+      end
+
+      def detail_for(body)
+        text = body.is_a?(Hash) ? body["message"] || body["error"] : body
+        text = text.to_s.gsub(/\s+/, " ").strip
+        text.empty? ? nil : text[0, 500]
+      end
+
+      # La requête est écartée pour garder un message stable : elle porte filtres et curseurs.
+      def request_label(env)
+        "(#{env.method.to_s.upcase} #{env.url.path})" if env.url
+      end
+
+      def retry_after(env)
+        value = env.response_headers && env.response_headers[RETRY_AFTER_HEADER]
+        Integer(value.to_s, 10) if value.to_s.match?(/\A\d+\z/)
+      end
+    end
+  end
+end

data/lib/pennylane/middleware/rate_limit.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Middleware
+    # Pennylane accepte 25 requêtes par fenêtre de 5 secondes et par token, puis répond 429 avec
+    # un `retry-after` en secondes. Une requête refusée n'a pas été traitée : la rejouer est sans
+    # risque, dépôt compris.
+    class RateLimit < Faraday::Middleware
+      DEFAULT_WAIT = 1
+
+      # Options en hash et non en mots-clés : Faraday 0.9 les transmet en argument positionnel.
+      def initialize(app, options = {})
+        super(app)
+        @retries = options.fetch(:retries)
+        @sleeper = options.fetch(:sleeper) { Kernel.method(:sleep) }
+      end
+
+      def call(env)
+        body = env.body
+        attempts = 0
+
+        begin
+          reset(env, body)
+          @app.call(env)
+        rescue RateLimitError => e
+          raise if attempts >= @retries
+
+          attempts += 1
+          @sleeper.call(e.retry_after || DEFAULT_WAIT)
+          retry
+        end
+      end
+
+      private
+
+      # Le corps de `env` porte la requête à l'aller et la réponse au retour : sans restauration,
+      # 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
+    end
+  end
+end

data/lib/pennylane/multipart.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module Pennylane
+  # Faraday 2 a sorti l'envoi multipart de son cœur (gem faraday-multipart) : le corps est assemblé
+  # ici pour rester sur la seule dépendance Faraday, de la 0.9 à la 2.
+  class Multipart
+    CRLF = "\r\n"
+
+    attr_reader :boundary
+
+    def initialize(boundary: "pennylane-#{SecureRandom.hex(16)}")
+      @boundary = boundary
+      @parts = []
+    end
+
+    def add_file(name, content, filename:, content_type:)
+      add(name, content, content_type: content_type, filename: filename)
+    end
+
+    def add_json(name, value)
+      add(name, JSON.generate(value), content_type: "application/json")
+    end
+
+    def content_type
+      "multipart/form-data; boundary=#{boundary}"
+    end
+
+    def body
+      body = String.new(encoding: Encoding::BINARY)
+      @parts.each { |part| body << "--#{boundary}#{CRLF}".b << part << CRLF.b }
+      body << "--#{boundary}--#{CRLF}".b
+    end
+
+    private
+
+    def add(name, content, content_type:, filename: nil)
+      disposition = %(form-data; name="#{name}")
+      disposition += %(; filename="#{filename.to_s.gsub(/["\\\r\n]/, "_")}") if filename
+      headers = "Content-Disposition: #{disposition}#{CRLF}Content-Type: #{content_type}#{CRLF}#{CRLF}"
+      @parts << (headers.b << content.to_s.b)
+      self
+    end
+  end
+end

data/lib/pennylane/resources/base.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Resources
+    class Base
+      def initialize(connection)
+        @connection = connection
+      end
+
+      def inspect
+        "#<#{self.class.name}>"
+      end
+
+      private
+
+      attr_reader :connection
+
+      def get(path, params = {})
+        connection.get(path, params.compact).body
+      end
+
+      def post(path, body)
+        connection.post(path, body).body
+      end
+
+      def post_multipart(path, multipart)
+        response = connection.post(path) do |request|
+          request.headers["Content-Type"] = multipart.content_type
+          request.body = multipart.body
+        end
+        response.body
+      end
+
+      def page(path, params, item_class)
+        Entities::Page.new(get(path, params), item_class: item_class)
+      end
+
+      def paginate(&fetch_page)
+        Enumerator.new do |yielder|
+          cursor = nil
+          loop do
+            current = fetch_page.call(cursor)
+            current.each { |item| yielder << item }
+            break unless current.more? && current.next_cursor
+
+            cursor = current.next_cursor
+          end
+        end
+      end
+
+      # Chaque ressource listable déclare FILTER, SORT_FIELDS et MAX_LIMIT.
+      def list_params(filters, sort, limit)
+        {
+          "filter" => self.class::FILTER.to_param(filters),
+          "sort" => sort_param(sort),
+          "limit" => limit_param(limit, self.class::MAX_LIMIT)
+        }
+      end
+
+      def sort_param(sort)
+        return nil if sort.nil?
+
+        fields = self.class::SORT_FIELDS
+        value = sort.to_s
+        return value if fields.include?(value.sub(/\A[+-]/, ""))
+
+        raise ArgumentError, "tri impossible sur #{sort.inspect} (attendus : #{fields.join(", ")})"
+      end
+
+      def limit_param(limit, max)
+        return nil if limit.nil?
+
+        value = Integer(limit.to_s, 10)
+        raise ArgumentError unless value.between?(1, max)
+
+        value
+      rescue ArgumentError
+        raise ArgumentError, "limit hors bornes : #{limit.inspect} (1 à #{max})"
+      end
+
+      def normalize_id(id, label = "identifiant")
+        value = id.respond_to?(:id) ? id.id : id
+        return Integer(value.to_s, 10) if value.to_s.match?(/\A[1-9]\d*\z/)
+
+        raise ArgumentError, "#{label} invalide : #{id.inspect}"
+      end
+    end
+  end
+end

data/lib/pennylane/resources/customer_invoices.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Resources
+    class CustomerInvoices < Base
+      FILTER = Filter.new(
+        "id" => Filter::COMPARISON,
+        "date" => Filter::COMPARISON,
+        "customer_id" => Filter::COMPARISON,
+        "billing_subscription_id" => Filter::COMPARISON,
+        "quote_id" => Filter::COMPARISON,
+        "invoice_number" => Filter::INCLUSION,
+        "flow_id" => Filter::INCLUSION,
+        "draft" => %w[eq],
+        "credit_note" => %w[eq],
+        "external_reference" => %w[eq],
+        "category_id" => %w[in]
+      )
+
+      SORT_FIELDS = %w[id date].freeze
+      MAX_LIMIT = 100
+      MAX_CHANGES_LIMIT = 1000
+      PDF_SIGNATURE = "%PDF-"
+      DUPLICATE_ID = /document with ID (\d+) already exists/.freeze
+
+      # Un fichier déjà déposé est refusé en DuplicateInvoiceError : Pennylane reconnaît le doublon à
+      # son fichier (« already exists with such attachment »). Le fichier est lu en différé : juste
+      # après le dépôt, la facture n'a ni numéro ni montant, et `find_by_invoice_number` ne la trouve
+      # pas encore.
+      def import(file, customer_id: nil, filename: nil)
+        content, path_filename = read_pdf(file)
+        filename ||= path_filename
+        raise ArgumentError, "filename est requis pour un fichier sans chemin" if filename.nil?
+
+        multipart = Multipart.new.add_file("file", content, filename: filename, content_type: "application/pdf")
+        unless customer_id.nil?
+          multipart.add_json("invoice_options", "customer_id" => normalize_id(customer_id, "customer_id"))
+        end
+        Entities::EInvoiceImport.new(post_multipart("customer_invoices/e_invoices/imports", multipart))
+      rescue ConflictError => e
+        raise DuplicateInvoiceError.new(e.message, invoice_id: e.message[DUPLICATE_ID, 1]&.to_i,
+                                                   status: e.status, body: e.body)
+      end
+
+      def find(id)
+        Entities::CustomerInvoice.new(get("customer_invoices/#{normalize_id(id)}"))
+      end
+
+      # Pennylane accepte deux factures de même numéro si leurs fichiers diffèrent : la plus ancienne
+      # est rendue, l'API listant par défaut les plus récentes d'abord.
+      def find_by_invoice_number(invoice_number)
+        raise ArgumentError, "numéro de facture manquant" if invoice_number.to_s.strip.empty?
+
+        list(filters: { invoice_number: invoice_number.to_s }, sort: "id", limit: 1).first
+      end
+
+      def find_many(ids)
+        ids = ids.map { |id| normalize_id(id) }.uniq
+        ids.each_slice(MAX_LIMIT).flat_map { |slice| list(filters: { id: { in: slice } }, limit: MAX_LIMIT).to_a }
+      end
+
+      def list(filters: {}, sort: nil, limit: nil, cursor: nil)
+        page("customer_invoices", list_params(filters, sort, limit).merge("cursor" => cursor),
+             Entities::CustomerInvoice)
+      end
+
+      # Le curseur ne retient pas les filtres : ils repartent avec chaque page.
+      def all(filters: {}, sort: nil, limit: MAX_LIMIT)
+        params = list_params(filters, sort, limit)
+        paginate { |cursor| page("customer_invoices", params.merge("cursor" => cursor), Entities::CustomerInvoice) }
+      end
+
+      def payments(invoice_id)
+        each_of("customer_invoices/#{normalize_id(invoice_id)}/payments", Entities::Payment).to_a
+      end
+
+      def matched_transactions(invoice_id)
+        each_of("customer_invoices/#{normalize_id(invoice_id)}/matched_transactions", Entities::MatchedTransaction).to_a
+      end
+
+      # Accepte une facture déjà lue, par exemple via `find_many`, pour éviter de la relire.
+      def settlement(invoice)
+        invoice = find(invoice) unless invoice.is_a?(Entities::CustomerInvoice)
+        Entities::Settlement.new(invoice, matched_transactions(invoice.id))
+      end
+
+      # Journal des créations, modifications et suppressions, du plus ancien au plus récent.
+      # L'API ne le conserve que quatre semaines : un `since` plus ancien est refusé en 422.
+      def changes(since: nil, limit: MAX_CHANGES_LIMIT)
+        params = { "start_date" => start_date_param(since), "limit" => limit_param(limit, MAX_CHANGES_LIMIT) }
+        # La date et le curseur s'excluent : la date ne sert qu'à la première page.
+        paginate do |cursor|
+          page("changelogs/customer_invoices", cursor ? params.merge("start_date" => nil, "cursor" => cursor) : params,
+               Entities::Change)
+        end
+      end
+
+      private
+
+      def each_of(path, item_class)
+        paginate { |cursor| page(path, { "limit" => MAX_LIMIT, "cursor" => cursor }, item_class) }
+      end
+
+      def start_date_param(since)
+        time = case since
+               when nil then return nil
+               when Time then since
+               when DateTime then since.to_time
+               when Date then Time.utc(since.year, since.month, since.day)
+               else raise ArgumentError, "since doit être une Time, une DateTime ou une Date : #{since.inspect}"
+               end
+        time.utc.iso8601(6)
+      end
+
+      # Un PDF peut légalement précéder sa signature de quelques octets.
+      def read_pdf(file)
+        content, filename =
+          if file.respond_to?(:read)
+            [file.read, file.respond_to?(:path) && file.path ? File.basename(file.path) : nil]
+          else
+            [File.binread(file.to_s), File.basename(file.to_s)]
+          end
+        raise ArgumentError, "le fichier n'est pas un PDF" unless content.to_s.b[0, 1024].include?(PDF_SIGNATURE)
+
+        [content, filename]
+      end
+    end
+  end
+end

data/lib/pennylane/resources/customers.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Pennylane
+  module Resources
+    class Customers < Base
+      FILTER = Filter.new(
+        "id" => Filter::COMPARISON,
+        "customer_type" => %w[eq not_eq],
+        "ledger_account_id" => %w[eq not_eq],
+        "name" => %w[start_with eq],
+        "external_reference" => %w[start_with eq not_eq in not_in],
+        "reg_no" => Filter::INCLUSION,
+        "emails" => %w[in]
+      )
+
+      SORT_FIELDS = %w[id].freeze
+      MAX_LIMIT = 100
+
+      COMMON_ATTRIBUTES = %w[
+        ledger_account phone billing_address delivery_address payment_conditions billing_iban recipient reference
+        notes emails external_reference billing_language
+      ].freeze
+      ATTRIBUTES = {
+        "company" => %w[name vat_number reg_no] + COMMON_ATTRIBUTES,
+        "individual" => %w[first_name last_name] + COMMON_ATTRIBUTES
+      }.freeze
+      REQUIRED_ATTRIBUTES = {
+        "company" => %w[name billing_address],
+        "individual" => %w[first_name last_name billing_address]
+      }.freeze
+      ADDRESS_FIELDS = %w[address postal_code city country_alpha2].freeze
+      ADDRESSES = %w[billing_address delivery_address].freeze
+      SIREN = /\A\d{9}\z/.freeze
+      SIRET = /\A\d{14}\z/.freeze
+
+      def find(id)
+        Entities::Customer.new(get("customers/#{normalize_id(id)}"))
+      end
+
+      # La référence externe est unique dans une société : c'est la clé de correspondance avec les
+      # clients de l'application hôte.
+      def find_by_external_reference(external_reference)
+        raise ArgumentError, "référence externe manquante" if external_reference.to_s.strip.empty?
+
+        list(filters: { external_reference: external_reference.to_s }, limit: 1).first
+      end
+
+      def find_by_reg_no(reg_no)
+        raise ArgumentError, "numéro d'immatriculation manquant" if reg_no.to_s.strip.empty?
+
+        list(filters: { reg_no: reg_no.to_s }, sort: "id", limit: 1).first
+      end
+
+      # Retrouve une entreprise par son SIREN, ou par le SIREN de son SIRET, et la crée sinon avec
+      # `attributes`, vérifiés avant tout appel. Le client créé porte le SIREN en `reg_no`. Parmi
+      # plusieurs clients de même SIREN, le plus ancien est rendu.
+      def find_or_create_by(siren_or_siret, **attributes)
+        reg_nos = reg_nos_for(siren_or_siret)
+        attributes = attributes.transform_keys(&:to_s)
+        if attributes.key?("reg_no")
+          raise ArgumentError, "reg_no est tiré du SIREN ou du SIRET passé en premier argument"
+        end
+
+        attributes["reg_no"] = reg_nos.first
+        check_attributes!("company", attributes)
+
+        list(filters: { reg_no: { in: reg_nos } }, sort: "id", limit: 1).first || post_customer("company", attributes)
+      end
+
+      def list(filters: {}, sort: nil, limit: nil, cursor: nil)
+        page("customers", list_params(filters, sort, limit).merge("cursor" => cursor), Entities::Customer)
+      end
+
+      def all(filters: {}, sort: nil, limit: MAX_LIMIT)
+        params = list_params(filters, sort, limit)
+        paginate { |cursor| page("customers", params.merge("cursor" => cursor), Entities::Customer) }
+      end
+
+      # Vérifié avant l'appel : l'API refuse un attribut inconnu ou manquant d'un unique « NotOneOf »
+      # qui ne nomme pas le champ en cause.
+      def create(customer_type:, **attributes)
+        type = customer_type.to_s
+        attributes = attributes.transform_keys(&:to_s)
+        check_attributes!(type, attributes)
+
+        post_customer(type, attributes)
+      end
+
+      private
+
+      def post_customer(type, attributes)
+        Entities::Customer.new(post("customers", attributes.merge("customer_type" => type)))
+      end
+
+      # Le SIRET est cherché avec son SIREN : `reg_no` peut avoir été saisi sous l'une ou l'autre forme.
+      def reg_nos_for(siren_or_siret)
+        value = siren_or_siret.to_s.delete(" ")
+        return [value] if value.match?(SIREN)
+        return [value[0, 9], value] if value.match?(SIRET)
+
+        raise ArgumentError, "SIREN (9 chiffres) ou SIRET (14 chiffres) attendu : #{siren_or_siret.inspect}"
+      end
+
+      def check_attributes!(type, attributes)
+        allowed = ATTRIBUTES.fetch(type) do
+          raise ArgumentError, "type de client inconnu : #{type.inspect} (attendus : #{ATTRIBUTES.keys.join(", ")})"
+        end
+        refuse!(attributes.keys - allowed, "attributs inconnus pour un client #{type}")
+        refuse!(REQUIRED_ATTRIBUTES.fetch(type).select { |name| blank?(attributes[name]) },
+                "attributs requis pour un client #{type}")
+
+        ADDRESSES.each { |name| check_address!(name, attributes[name]) if attributes.key?(name) }
+      end
+
+      def check_address!(name, address)
+        raise ArgumentError, "#{name} doit être un hash" unless address.is_a?(Hash)
+
+        address = address.transform_keys(&:to_s)
+        refuse!(address.keys - ADDRESS_FIELDS, "champs inconnus dans #{name}")
+        refuse!(ADDRESS_FIELDS.select { |field| blank?(address[field]) }, "champs requis dans #{name}")
+      end
+
+      def refuse!(names, message)
+        raise ArgumentError, "#{message} : #{names.join(", ")}" if names.any?
+      end
+
+      def blank?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?) || value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/pennylane/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pennylane-client
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Hôtentic
@@ -51,6 +51,28 @@ files:
 - bin/setup
 - lib/pennylane-client.rb
 - lib/pennylane.rb
+- lib/pennylane/client.rb
+- lib/pennylane/configuration.rb
+- lib/pennylane/connection.rb
+- lib/pennylane/entities/base.rb
+- lib/pennylane/entities/change.rb
+- lib/pennylane/entities/customer.rb
+- lib/pennylane/entities/customer_invoice.rb
+- lib/pennylane/entities/e_invoice_import.rb
+- lib/pennylane/entities/matched_transaction.rb
+- lib/pennylane/entities/page.rb
+- lib/pennylane/entities/payment.rb
+- lib/pennylane/entities/settlement.rb
+- lib/pennylane/errors.rb
+- lib/pennylane/filter.rb
+- lib/pennylane/middleware/encode_json.rb
+- lib/pennylane/middleware/parse_json.rb
+- lib/pennylane/middleware/raise_error.rb
+- lib/pennylane/middleware/rate_limit.rb
+- lib/pennylane/multipart.rb
+- lib/pennylane/resources/base.rb
+- lib/pennylane/resources/customer_invoices.rb
+- lib/pennylane/resources/customers.rb
 - lib/pennylane/version.rb
 - pennylane-client.gemspec
 homepage: https://hotentic.com