super_pdp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 80df88af44b2d803aa180b0d205329440167089782755f4ac1635b94a5066d54
+  data.tar.gz: 5083f9d514fb7163910a0d8ed9b3129762c1f561e11ceb50ec3f0f214148f56f
+SHA512:
+  metadata.gz: 252df23df32876233d65684b4afb80b2756e788a7b51b0d6dc3fc6cc3b504dd83a15064ab69ff49a09432fd97b2dcccf7d5fb32180d04fbf21f3b19577cb5baf
+  data.tar.gz: 2ce4577ad5003b603dba86a1bdd1946bc45735b3631c686e82e883ff236e547152478b5992bc18375241fc4a697248a63d4631caa6651c0e54dd11e81e27d895

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Thomas Demoncy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,88 @@
+# super_pdp
+
+Thin, dependency-free Ruby client for the [SUPER PDP API](https://api.superpdp.tech) —
+send and receive invoices under France's e-invoicing reform (Peppol network).
+
+Stdlib only (`net/http` + `json`). No Faraday, no generated model classes.
+
+> **Unofficial.** This is an independent, community-maintained client. It is
+> **not** affiliated with, endorsed by, or supported by SUPER PDP. "SUPER PDP"
+> and any related marks belong to their respective owners; they are used here
+> only to describe what this gem talks to (nominative use). The gem calls the
+> publicly documented HTTP API — no proprietary code is included — and is
+> provided "as is" under the MIT license, with no warranty. The maintainer may
+> update or **yank this gem from RubyGems at any time**; pin a version if you
+> depend on it.
+
+## Install
+
+```ruby
+gem "super_pdp"
+```
+
+## Auth
+
+Two modes, both OAuth2:
+
+```ruby
+# Client credentials — acts on your own data (api-key-like). Token is fetched
+# and refreshed automatically.
+pdp = SuperPDP.new(client_id: "...", client_secret: "...")
+
+# Bearer token — acts on a user's behalf. You obtain the token yourself via the
+# authorization_code flow (/oauth2/authorize) and pass it in.
+pdp = SuperPDP.new(access_token: "user-token")
+```
+
+## Use
+
+```ruby
+pdp.companies_me
+pdp.create_invoice({ en_invoice: { ... } })   # body is a positional Hash
+pdp.create_invoice({ en_invoice: { ... } }, expand: %w[events])  # + query params
+pdp.invoice(42, expand: %w[en_invoice events])
+pdp.download_invoice(42)              # raw bytes (PDF/XML), not JSON
+pdp.create_invoice_event(invoice_id: 42, status: "fr:204")
+
+# Cursor pagination handled for you:
+pdp.each_item("/invoices", direction: "outgoing").each do |inv|
+  puts inv["id"]
+end
+```
+
+Named helpers exist for every endpoint (companies, invoices, invoice_events,
+ereportings, b2c_transactions, b2c_payments, directory_entries,
+french_directory, validation_reports, oauth2_sessions). For anything not
+wrapped, drop to the raw verbs:
+
+```ruby
+pdp.get("/invoices", limit: 10)
+pdp.post("/some/new/route", { key: "value" })
+```
+
+Responses are parsed JSON (`Hash`/`Array`). Non-2xx raises `SuperPDP::APIError`
+(`#status`, `#body`).
+
+## Test
+
+```
+bundle exec rake test     # or: bundle exec rake  (runs tests + rubocop)
+```
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). In short:
+open an issue to discuss anything non-trivial, then send a PR with `bundle exec
+rake` (tests + rubocop) passing.
+
+## Releasing (maintainers)
+
+Bump `SuperPDP::VERSION`, update `CHANGELOG.md`, then:
+
+```
+bundle exec rake release   # tags the version and pushes the .gem to RubyGems
+```
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/lib/super_pdp/client.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module SuperPDP
+  # Thin HTTP client for the SUPER PDP API.
+  #
+  # Auth: pass an +access_token+ directly (e.g. one you obtained via the
+  # authorization_code flow to act on a user's behalf), or pass
+  # +client_id+/+client_secret+ to have the client fetch and refresh a
+  # client_credentials token automatically (acts on your own data, api-key-like).
+  class Client
+    DEFAULT_BASE_URL = "https://api.superpdp.tech"
+    API_PREFIX = "/v1.beta"
+
+    attr_reader :base_url
+
+    def initialize(access_token: nil, client_id: nil, client_secret: nil,
+                   base_url: DEFAULT_BASE_URL, open_timeout: 10, read_timeout: 60)
+      @access_token = access_token
+      @client_id = client_id
+      @client_secret = client_secret
+      @base_url = base_url
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @token_expires_at = nil
+      @token_mutex = Mutex.new
+
+      return if access_token || (client_id && client_secret)
+
+      raise ArgumentError, "provide access_token, or client_id and client_secret"
+    end
+
+    # --- Resource helpers (thin wrappers over the raw verbs) --------------
+
+    def companies_me(**params) = get("/companies/me", params)
+    def enroll_company(body) = post("/companies", body)
+    def update_company_vat_regime(body) = patch("/companies", body)
+
+    def invoices(**params) = get("/invoices", params)
+    def invoice(id, **params) = get("/invoices/#{id}", params)
+    def create_invoice(body, **params) = post("/invoices", body, params)
+    def convert_invoice(body, **params) = post("/invoices/convert", body, params)
+    def validation_report(body) = post("/validation_reports", body)
+    def generate_test_invoice(**params) = get("/invoices/generate_test_invoice", params)
+
+    # Raw invoice file bytes (not JSON) — returns the String body.
+    def download_invoice(id, **params) = request(:get, "/invoices/#{id}/download", query: params, raw: true)
+
+    def invoice_events(**params) = get("/invoice_events", params)
+    def create_invoice_event(body) = post("/invoice_events", body)
+
+    def ereportings(**params) = get("/ereportings", params)
+    def ereporting(id, **params) = get("/ereportings/#{id}", params)
+    def preview_ereporting(**params) = get("/ereportings/preview", params)
+
+    def b2c_transactions(**params) = get("/b2c_transactions", params)
+    def create_b2c_transactions(body) = post("/b2c_transactions", body)
+    def b2c_payments(**params) = get("/b2c_payments", params)
+    def create_b2c_payment(body) = post("/b2c_payments", body)
+
+    def directory_entries(**params) = get("/directory_entries", params)
+    def directory_entry(id, **params) = get("/directory_entries/#{id}", params)
+    def create_directory_entry(body) = post("/directory_entries", body)
+    def delete_directory_entry(id) = delete("/directory_entries/#{id}")
+
+    def french_directory_companies(**params) = get("/french_directory/companies", params)
+    def french_directory_entries(**params) = get("/french_directory/entries", params)
+
+    def oauth2_session_me(**params) = get("/oauth2_sessions/me", params)
+
+    # Iterate a list endpoint across all pages, yielding each item.
+    # Uses the API's cursor pagination (starting_after_id + has_after).
+    # Returns an Enumerator when no block is given.
+    def each_item(path, **params, &block)
+      return enum_for(:each_item, path, **params) unless block_given?
+
+      cursor = params[:starting_after_id]
+      loop do
+        page = get(path, params.merge(starting_after_id: cursor).compact)
+        data = page["data"] || []
+        data.each(&block)
+        break unless page["has_after"] && !data.empty?
+
+        cursor = data.last["id"]
+      end
+    end
+
+    # --- Raw verbs --------------------------------------------------------
+
+    def get(path, query = {}) = request(:get, path, query: query)
+    def post(path, body = {}, query = {}) = request(:post, path, body: body, query: query)
+    def patch(path, body = {}, query = {}) = request(:patch, path, body: body, query: query)
+    def delete(path, query = {}) = request(:delete, path, query: query)
+
+    def request(method, path, query: {}, body: nil, raw: false)
+      uri = build_uri(path, query)
+      req = build_request(method, uri, body)
+      req["Authorization"] = "Bearer #{token}"
+
+      res = http(uri).request(req)
+      handle_response(res, raw: raw)
+    end
+
+    private
+
+    def build_uri(path, query)
+      full = path.start_with?("/v1") || path.start_with?("http") ? path : "#{API_PREFIX}#{path}"
+      uri = URI.join(@base_url, full)
+      q = flatten_query(query || {})
+      uri.query = URI.encode_www_form(q) unless q.empty?
+      uri
+    end
+
+    # Encode array params as repeated `key[]=v` pairs (matches expand[] etc).
+    def flatten_query(query)
+      query.compact.flat_map do |k, v|
+        v.is_a?(Array) ? v.map { |item| ["#{k}[]", item] } : [[k.to_s, v]]
+      end
+    end
+
+    def build_request(method, uri, body)
+      klass = {
+        get: Net::HTTP::Get, post: Net::HTTP::Post,
+        patch: Net::HTTP::Patch, delete: Net::HTTP::Delete
+      }.fetch(method)
+      req = klass.new(uri)
+      req["Accept"] = "application/json"
+      if body
+        req["Content-Type"] = "application/json"
+        req.body = body.is_a?(String) ? body : JSON.generate(body)
+      end
+      req
+    end
+
+    def http(uri)
+      Net::HTTP.new(uri.host, uri.port).tap do |h|
+        h.use_ssl = uri.scheme == "https"
+        h.open_timeout = @open_timeout
+        h.read_timeout = @read_timeout
+      end
+    end
+
+    def handle_response(res, raw:)
+      status = res.code.to_i
+      body = raw ? res.body : parse_json(res.body)
+      return body if status.between?(200, 299)
+
+      raise APIError.new(status, body)
+    end
+
+    def parse_json(str)
+      return nil if str.nil? || str.empty?
+
+      JSON.parse(str)
+    rescue JSON::ParserError
+      str
+    end
+
+    # --- OAuth2 -----------------------------------------------------------
+
+    def token
+      # Lock so a shared client in a threaded server (Puma/Sidekiq) doesn't
+      # race two concurrent refreshes. Double-checked inside the lock.
+      @token_mutex.synchronize do
+        return @access_token if @access_token && !expired?
+
+        fetch_client_credentials_token
+      end
+    end
+
+    def expired?
+      @token_expires_at && Time.now >= @token_expires_at
+    end
+
+    def fetch_client_credentials_token
+      unless @client_id && @client_secret
+        raise AuthError, "access_token missing/expired and no client credentials to refresh it"
+      end
+
+      uri = URI.join(@base_url, "/oauth2/token")
+      req = Net::HTTP::Post.new(uri)
+      req["Accept"] = "application/json"
+      req.set_form_data(
+        grant_type: "client_credentials",
+        client_id: @client_id,
+        client_secret: @client_secret
+      )
+      res = http(uri).request(req)
+      raise AuthError, "token request failed (#{res.code}): #{res.body}" unless res.code.to_i.between?(200, 299)
+
+      data = JSON.parse(res.body)
+      @access_token = data.fetch("access_token")
+      # Refresh 60s early. Default to 1h if the server omits expires_in.
+      @token_expires_at = Time.now + (data["expires_in"] || 3600).to_i - 60
+      @access_token
+    end
+  end
+end

data/lib/super_pdp/error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SuperPDP
+  class Error < StandardError; end
+
+  # Raised for any non-2xx HTTP response. Carries the status and parsed body.
+  class APIError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body)
+      @status = status
+      @body = body
+      message = body.is_a?(Hash) ? (body["message"] || body["error"] || body.to_s) : body.to_s
+      super("SuperPDP API error #{status}: #{message}")
+    end
+  end
+
+  class AuthError < Error; end
+end

data/lib/super_pdp/version.rb

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

data/lib/super_pdp.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative "super_pdp/version"
+require_relative "super_pdp/error"
+require_relative "super_pdp/client"
+
+module SuperPDP
+  def self.new(...) = Client.new(...)
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: super_pdp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Thomas Demoncy
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.35'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.35'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+description: Thin, dependency-free Ruby client for the SUPER PDP API (France electronic
+  invoicing reform / Peppol).
+email:
+- thomas.demoncy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/super_pdp.rb
+- lib/super_pdp/client.rb
+- lib/super_pdp/error.rb
+- lib/super_pdp/version.rb
+homepage: https://api.superpdp.tech
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://api.superpdp.tech
+  source_code_uri: https://github.com/ThomasDmnc/supepdp-gem
+  changelog_uri: https://github.com/ThomasDmnc/supepdp-gem/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the SUPER PDP e-invoicing API
+test_files: []