api_particulier 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 69af0dca4424823c2fa2cbaba141f4ccde38d45309ce3f4a878e3ae6105728aa
+  data.tar.gz: 95b4443df163a996ca72416060d212b69fc2efc4dc00981699aa3d486e285993
+SHA512:
+  metadata.gz: d5e1f0af171ee5808171f3e0d13b5cae816d0932422ba7eb5b083b148c339e31f2d9f513f0e874d71246c92062a463a2c9faac8c6d4143b9385685e7817da2b9
+  data.tar.gz: 6c98f422268ae3cecf8f9e56296a1b3df56e5fa499e5b31f541b0e6c1598e55587d8ac5ad963275c87da12f9dd4689c5e7afd7de966a7ad8514e6601cb046ba9

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `api_particulier` (Ruby) are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/) and the project
+adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+- Initial release — conforms to `clients/SPECS.md` §1–§20.
+- `production` / `staging` environments with `base_url` override.
+- `BearerToken` auth strategy with a pluggable `Auth::Strategy` seam.
+- Client-level `default_params` with per-call override for `recipient`
+  (Particulier does not require `context` / `object`).
+- Local SIRET / SIREN validation before any HTTP call.
+- `Response` value object (`data`, `links`, `meta`, `raw`, `http_status`,
+  `headers`, `rate_limit`).
+- Full JSON:API exception hierarchy matching `clients/SPECS.md` §6.
+- `RateLimit-*` header parsing and `retry_after` on `RateLimitError`.
+- Opt-in retry middleware via `faraday-retry`.
+- 9 resource modules scaffolded from the OpenAPI spec, grouped by provider.
+- Logging middleware redacts query strings by default (PII protection).
+- `examples/{basic,error_handling,retry}.rb`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DINUM (Direction Interministérielle du Numérique)
+
+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,66 @@
+# api_particulier
+
+Ruby client for [API Particulier v3](https://particulier.api.gouv.fr). Conforms
+to [`clients/SPECS.md`](../../SPECS.md).
+
+## Installation
+
+```ruby
+# Gemfile
+gem 'api_particulier'
+```
+
+## Configuration
+
+```ruby
+client = ApiParticulier::Client.new(
+  token: ENV['API_PARTICULIER_TOKEN'],
+  environment: :staging, # or :production (default)
+  default_params: { recipient: '13002526500013' }
+)
+```
+
+ENV vars: `API_PARTICULIER_TOKEN`, `API_PARTICULIER_ENV`,
+`API_PARTICULIER_BASE_URL`.
+
+## Quickstart
+
+```ruby
+response = client.ants.extrait_immatriculation_vehicule(immatriculation: 'AA-123-BB')
+response.data         # => { "titulaire" => { ... } }
+response.rate_limit.remaining
+```
+
+Low-level escape hatch: `client.get(path, params: {...})`.
+
+## Error handling
+
+See the entreprise README and `clients/SPECS.md` §6 — same hierarchy applies
+under `ApiParticulier::Commons::*`.
+
+## Testing
+
+No embedded mock mode. Stub with WebMock:
+
+```ruby
+stub_request(:get, %r{https://staging\.particulier\.api\.gouv\.fr/v3/ants/.+})
+  .with(headers: { 'Authorization' => 'Bearer test' })
+  .to_return(status: 200,
+             headers: { 'Content-Type' => 'application/json' },
+             body: { data: {}, links: {}, meta: {} }.to_json)
+```
+
+PII notice: the default logger redacts the query string on Particulier
+requests, since query params carry personal data (names, DOB, INE).
+
+## Development
+
+Shared code comes from `clients/ruby/commons/`; resources are scaffolded from
+the OpenAPI spec:
+
+```sh
+clients/ruby/bin/sync_commons
+clients/ruby/bin/scaffold_resources --api particulier
+```
+
+CI checks both are in sync.

data/lib/api_particulier/client.rb

@@ -0,0 +1,76 @@
+require_relative 'commons'
+
+# <scaffold:requires:begin>
+require_relative 'resources/ants'
+require_relative 'resources/cnous'
+require_relative 'resources/dsnj'
+require_relative 'resources/dss'
+require_relative 'resources/france_travail'
+require_relative 'resources/gip_mds'
+require_relative 'resources/men'
+require_relative 'resources/mesri'
+require_relative 'resources/sdh'
+# <scaffold:requires:end>
+
+module ApiParticulier
+  BASE_URLS = {
+    Commons::Configuration::PRODUCTION => 'https://particulier.api.gouv.fr',
+    Commons::Configuration::STAGING => 'https://staging.particulier.api.gouv.fr'
+  }.freeze
+
+  class Client < Commons::ClientBase
+    REQUIRED_PARAMS = %i[recipient].freeze
+    SIRET_PARAMS = %i[recipient].freeze
+
+    def initialize(token: nil, environment: nil, default_params: {}, base_url: nil, auth_strategy: nil, **opts)
+      env_token = token || ENV.fetch('API_PARTICULIER_TOKEN', nil)
+      env_env = (environment || ENV.fetch('API_PARTICULIER_ENV', :production)).to_sym
+
+      config = Commons::Configuration.new(
+        base_urls: BASE_URLS,
+        token: env_token,
+        auth_strategy: auth_strategy,
+        environment: env_env,
+        base_url: base_url || ENV.fetch('API_PARTICULIER_BASE_URL', nil),
+        default_params: default_params,
+        user_agent: opts[:user_agent] || Commons::UserAgent.build(product: 'api-particulier-ruby', version: VERSION),
+        open_timeout: opts[:open_timeout] || Commons::Configuration::DEFAULT_OPEN_TIMEOUT,
+        read_timeout: opts[:read_timeout] || Commons::Configuration::DEFAULT_READ_TIMEOUT,
+        retry: opts[:retry],
+        logger: opts[:logger],
+        adapter: opts[:adapter]
+      )
+      super(config, product: :particulier)
+    end
+
+    # <scaffold:resources:begin>
+    def ants
+      @ants ||= Resources::Ants.new(self)
+    end
+    def cnous
+      @cnous ||= Resources::Cnous.new(self)
+    end
+    def dsnj
+      @dsnj ||= Resources::Dsnj.new(self)
+    end
+    def dss
+      @dss ||= Resources::Dss.new(self)
+    end
+    def france_travail
+      @france_travail ||= Resources::FranceTravail.new(self)
+    end
+    def gip_mds
+      @gip_mds ||= Resources::GipMds.new(self)
+    end
+    def men
+      @men ||= Resources::Men.new(self)
+    end
+    def mesri
+      @mesri ||= Resources::Mesri.new(self)
+    end
+    def sdh
+      @sdh ||= Resources::Sdh.new(self)
+    end
+    # <scaffold:resources:end>
+  end
+end

data/lib/api_particulier/commons/auth/bearer_token.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+# DO NOT EDIT — generated from clients/ruby/commons/ (source digest: 903f3b3aca1a59a6cb1a53ab98f72c365486fc1f).
+# Regenerate via clients/ruby/bin/sync_commons.
+
+require_relative 'strategy'
+
+module ApiParticulier::Commons
+  module Auth
+    class BearerToken < Strategy
+      def initialize(token)
+        raise ArgumentError, 'token must be a non-empty string' if token.nil? || token.to_s.strip.empty?
+
+        @token = token.to_s
+      end
+
+      def apply(request)
+        request.headers['Authorization'] = "Bearer #{@token}"
+      end
+    end
+  end
+end

data/lib/api_particulier/commons/auth/strategy.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+# DO NOT EDIT — generated from clients/ruby/commons/ (source digest: 903f3b3aca1a59a6cb1a53ab98f72c365486fc1f).
+# Regenerate via clients/ruby/bin/sync_commons.
+
+module ApiParticulier::Commons
+  module Auth
+    class Strategy
+      def apply(request)
+        raise NotImplementedError, "#{self.class} must implement #apply(request)"
+      end
+    end
+  end
+end

data/lib/api_particulier/commons/client_base.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+# DO NOT EDIT — generated from clients/ruby/commons/ (source digest: 903f3b3aca1a59a6cb1a53ab98f72c365486fc1f).
+# Regenerate via clients/ruby/bin/sync_commons.
+
+require 'faraday'
+begin
+  require 'faraday/retry'
+rescue LoadError
+  # faraday-retry is optional; the :retry middleware is only used when the
+  # consumer opts in.
+end
+
+require_relative 'middleware/authentication'
+require_relative 'middleware/logging'
+require_relative 'middleware/rate_limit'
+require_relative 'middleware/error_handler'
+require_relative 'middleware/envelope'
+require_relative 'response'
+require_relative 'siret'
+require_relative 'errors'
+
+module ApiParticulier::Commons
+  class ClientBase
+    attr_reader :configuration
+
+    REQUIRED_PARAMS = %i[recipient context object].freeze
+    SIRET_PARAMS = %i[recipient].freeze
+
+    def initialize(configuration, product:)
+      @configuration = configuration
+      @product = product
+      @connection = build_connection
+    end
+
+    def get(path, params: {}, headers: {})
+      merged = merge_params(params)
+      validate_required!(merged)
+      validate_sirets!(merged)
+
+      response = @connection.get(path, clean(merged), headers)
+      build_response(response)
+    end
+
+    private
+
+    def merge_params(params)
+      defaults = @configuration.default_params.transform_keys(&:to_s)
+      defaults.merge((params || {}).transform_keys(&:to_s))
+    end
+
+    def required_params_for(_params)
+      self.class::REQUIRED_PARAMS
+    end
+
+    def siret_params_for(_params)
+      self.class::SIRET_PARAMS
+    end
+
+    def validate_required!(params)
+      required_params_for(params).each do |key|
+        next unless blank?(params[key.to_s])
+
+        raise MissingParameterError, "required parameter #{key.inspect} is missing"
+      end
+    end
+
+    def validate_sirets!(params)
+      siret_params_for(params).each do |key|
+        value = params[key.to_s]
+        next if value.nil?
+
+        Siret.validate!(value, parameter: key)
+      end
+    end
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+
+    def clean(params)
+      params.reject { |_, v| v.nil? }
+    end
+
+    def build_response(response)
+      Response.new(
+        raw: response.body,
+        http_status: response.status,
+        headers: response.headers,
+        rate_limit: response.env[Middleware::RateLimitParser::ENV_KEY]
+      )
+    end
+
+    def build_connection
+      cfg = @configuration
+      Faraday.new(url: cfg.base_url) do |conn|
+        conn.options.open_timeout = cfg.open_timeout
+        conn.options.timeout = cfg.read_timeout
+
+        conn.headers['User-Agent'] = cfg.user_agent if cfg.user_agent
+        conn.headers['Accept'] = 'application/json'
+
+        if cfg.retry && defined?(Faraday::Retry)
+          conn.request :retry,
+                       max: cfg.retry.fetch(:max, 2),
+                       retry_statuses: cfg.retry.fetch(:on_status, [429, 502, 503]),
+                       methods: %i[get],
+                       interval: cfg.retry.fetch(:interval, 0.5),
+                       backoff_factor: cfg.retry.fetch(:backoff_factor, 2),
+                       exceptions: [
+                         ApiParticulier::Commons::RateLimitError,
+                         ApiParticulier::Commons::ProviderError,
+                         ApiParticulier::Commons::ProviderUnavailableError,
+                         ApiParticulier::Commons::TransportError
+                       ]
+        end
+
+        conn.use Middleware::Authentication, auth_strategy: cfg.auth_strategy
+        conn.use Middleware::Logging, logger: cfg.logger, redact_query: @product == :particulier
+
+        conn.use Middleware::RateLimitParser
+        conn.use Middleware::ErrorHandler
+        conn.use Middleware::Envelope
+
+        conn.adapter(cfg.adapter || Faraday.default_adapter)
+      end
+    end
+  end
+end

data/lib/api_particulier/commons/configuration.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+# DO NOT EDIT — generated from clients/ruby/commons/ (source digest: 903f3b3aca1a59a6cb1a53ab98f72c365486fc1f).
+# Regenerate via clients/ruby/bin/sync_commons.
+
+require_relative 'auth/bearer_token'
+
+module ApiParticulier::Commons
+  class Configuration
+    PRODUCTION = :production
+    STAGING = :staging
+    ENVIRONMENTS = [PRODUCTION, STAGING].freeze
+
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 30
+
+    attr_reader :base_url,
+                :environment,
+                :auth_strategy,
+                :default_params,
+                :open_timeout,
+                :read_timeout,
+                :retry,
+                :logger,
+                :user_agent,
+                :adapter
+
+    def initialize(
+      base_urls:,
+      token: nil,
+      auth_strategy: nil,
+      environment: PRODUCTION,
+      base_url: nil,
+      default_params: {},
+      open_timeout: DEFAULT_OPEN_TIMEOUT,
+      read_timeout: DEFAULT_READ_TIMEOUT,
+      retry: nil,
+      logger: nil,
+      user_agent: nil,
+      adapter: nil
+    )
+      @base_urls = base_urls
+      resolved_env = resolve_environment(environment)
+      @environment = resolved_env
+      @explicit_base_url = !base_url.nil?
+      @base_url = base_url || base_urls.fetch(resolved_env)
+      @auth_strategy = auth_strategy || build_bearer_strategy(token)
+      @default_params = default_params.freeze
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @retry = binding.local_variable_get(:retry)
+      @logger = logger
+      @user_agent = user_agent
+      @adapter = adapter
+      freeze
+    end
+
+    def with(**overrides)
+      self.class.new(**current_attrs.merge(overrides))
+    end
+    alias copy with
+
+    def production?
+      environment == PRODUCTION
+    end
+
+    def staging?
+      environment == STAGING
+    end
+
+    private
+
+    def current_attrs
+      {
+        base_urls: @base_urls,
+        auth_strategy: auth_strategy,
+        environment: environment,
+        base_url: @explicit_base_url ? base_url : nil,
+        default_params: default_params,
+        open_timeout: open_timeout,
+        read_timeout: read_timeout,
+        retry: @retry,
+        logger: logger,
+        user_agent: user_agent,
+        adapter: adapter
+      }
+    end
+
+    def resolve_environment(value)
+      env = value.to_sym
+      return env if ENVIRONMENTS.include?(env)
+
+      raise ArgumentError, "environment must be one of #{ENVIRONMENTS.inspect}; got #{value.inspect}"
+    end
+
+    def build_bearer_strategy(token)
+      return nil if token.nil?
+
+      Auth::BearerToken.new(token)
+    end
+  end
+end

data/lib/api_particulier/commons/errors.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+# DO NOT EDIT — generated from clients/ruby/commons/ (source digest: 903f3b3aca1a59a6cb1a53ab98f72c365486fc1f).
+# Regenerate via clients/ruby/bin/sync_commons.
+
+module ApiParticulier::Commons
+  class Error < StandardError
+    attr_reader :http_status, :errors, :method, :url
+
+    def initialize(message = nil, http_status: nil, errors: [], method: nil, url: nil)
+      super(message || default_message(http_status, errors))
+      @http_status = http_status
+      @errors = errors || []
+      @method = method
+      @url = url
+    end
+
+    def first_error
+      errors.first || {}
+    end
+
+    def first_error_code
+      first_error['code'] || first_error[:code]
+    end
+
+    def first_error_title
+      first_error['title'] || first_error[:title]
+    end
+
+    def first_error_detail
+      first_error['detail'] || first_error[:detail]
+    end
+
+    def first_error_source
+      first_error['source'] || first_error[:source]
+    end
+
+    def first_error_meta
+      first_error['meta'] || first_error[:meta] || {}
+    end
+
+    private
+
+    def default_message(http_status, errors)
+      first = (errors || []).first || {}
+      title = first['title'] || first[:title]
+      detail = first['detail'] || first[:detail]
+      parts = [http_status, title, detail].compact
+      parts.empty? ? self.class.name : parts.join(' — ')
+    end
+  end
+
+  class ClientError < Error; end
+  class AuthenticationError < ClientError; end
+  class AuthorizationError < ClientError; end
+  class NotFoundError < ClientError; end
+  class ConflictError < ClientError; end
+  class ValidationError < ClientError; end
+
+  class RateLimitError < ClientError
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  class ServerError < Error; end
+  class ProviderError < ServerError
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+  class ProviderUnavailableError < ServerError; end
+
+  class TransportError < Error; end
+
+  class InvalidSiretError < ArgumentError; end
+  class InvalidSirenError < ArgumentError; end
+  class MissingParameterError < ArgumentError; end
+end

data/lib/api_particulier/commons/middleware/authentication.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+# DO NOT EDIT — generated from clients/ruby/commons/ (source digest: 903f3b3aca1a59a6cb1a53ab98f72c365486fc1f).
+# Regenerate via clients/ruby/bin/sync_commons.
+
+require 'faraday'
+
+module ApiParticulier::Commons
+  module Middleware
+    class Authentication < Faraday::Middleware
+      def initialize(app, auth_strategy:)
+        super(app)
+        @auth_strategy = auth_strategy
+      end
+
+      def on_request(env)
+        return if @auth_strategy.nil?
+
+        request = RequestWrapper.new(env)
+        begin
+          @auth_strategy.apply(request)
+        rescue StandardError => e
+          raise ApiParticulier::Commons::AuthenticationError.new(
+            "auth strategy raised: #{e.message}",
+            method: env.method,
+            url: env.url.to_s
+          )
+        end
+      end
+
+      class RequestWrapper
+        def initialize(env)
+          @env = env
+        end
+
+        def headers
+          @env.request_headers
+        end
+
+        def method
+          @env.method
+        end
+
+        def url
+          @env.url
+        end
+      end
+    end
+  end
+end

data/lib/api_particulier/commons/middleware/envelope.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+# DO NOT EDIT — generated from clients/ruby/commons/ (source digest: 903f3b3aca1a59a6cb1a53ab98f72c365486fc1f).
+# Regenerate via clients/ruby/bin/sync_commons.
+
+require 'faraday'
+require 'json'
+
+module ApiParticulier::Commons
+  module Middleware
+    class Envelope < Faraday::Middleware
+      def on_complete(env)
+        body = env.body
+        return if body.nil? || body.is_a?(Hash) || body.is_a?(Array)
+        return unless body.is_a?(String) && !body.empty?
+
+        parsed =
+          begin
+            JSON.parse(body)
+          rescue JSON::ParserError
+            raise ApiParticulier::Commons::TransportError.new(
+              "invalid JSON body: #{body[0, 200]}",
+              method: env.method,
+              url: env.url.to_s
+            )
+          end
+
+        env.body = parsed
+      end
+    end
+  end
+end