toc_doc 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: beef9501f028dfc80d31fb212f9ff876b20b952801ce7712702144bfa572fb32
-  data.tar.gz: ade0bafa23b88557931944c4199e64b9f45c972814d5b7af4b6b343602ae32eb
+  metadata.gz: 50818c97b021143ebf2d502a867fb5f20a90299a822ec800b7d02ae4d20999eb
+  data.tar.gz: d4ef919a143957c2685fba1f28675786743922387b0703c521a6d5c0b9ab76c3
 SHA512:
-  metadata.gz: 5fcf8a1d6b3e3ef1e200bbd34c91922859f1c31ebb1ed208c6810d75470e56a63030c1f325f2ec9c39bbb54a73b97f831b5503d26528e34f62863f8a63cbedda
-  data.tar.gz: 20b38a89845bdf86a3b6effae5f47fbfc97e1d461b309a95a0c1a5b072bce2e9b6c58ee627719a07b02751b93e0edcfb309e552d6c6516998c3e34a8fb1ab2ef
+  metadata.gz: 9aa3dd68984a7cec38789a3a718db4f7c9db9a0335ae8e47744f24990dccb73de12e41903aee8806e06f579288769c13a5b9f82327a031dd3c2052d096ae33e5
+  data.tar.gz: 10725265d2117c4d93720c89f5c06360ea567377c6d21f9a848e26151de7039876ac9a7b1da936801f0eaf9a7b8141689e8389b5a2917f3d550a01847aa52767

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 ## [Unreleased]
 
+## [1.6.0] - 2026-03-30
+
+### Added
+
+- **Timeout configuration** — two new config keys: `connect_timeout` (TCP connect, default: `5`, env: `TOCDOC_CONNECT_TIMEOUT`) and `read_timeout` (response read, default: `10`, env: `TOCDOC_READ_TIMEOUT`); passed to Faraday as `open_timeout` and `timeout` respectively
+- **`per_page` guard** — `TocDoc::Configurable` now emits a warning when `per_page` exceeds the maximum value the Doctolib API can handle
+- **`TocDoc::Error` hierarchy** — structured error subclasses; `TocDoc::ResponseError` carries `status`, `body`, and `headers`; specific subclasses: `BadRequest` (400), `NotFound` (404), `UnprocessableEntity` (422), `TooManyRequests` (429), `ClientError` (other 4xx), `ServerError` (5xx); `TocDoc::ConnectionError` raised on network/transport failures
+- **`TocDoc::Middleware::RaiseError`** — reworked to map HTTP error codes to structured `TocDoc::Error` subclasses; wraps Faraday transport errors (`TimeoutError`, `ConnectionFailed`, `SSLError`) into `TocDoc::ConnectionError`
+- **`Default.reset!`** — class method to reset memoized middleware defaults, preventing middleware stack leak between configurations
+
+### Changed
+
+- **Max retry** — retry limit logic moved from `BaseMiddleware` into `TocDoc::Default`, eliminating the `BaseMiddleware` class; retry count now derived solely from `Default::MAX_RETRY`
+
 ## [1.5.0] - 2026-03-28
 
 ### Added

data/POTENTIAL_ENDPOINTS.md

@@ -3,16 +3,16 @@
 - Interesting JSONs [GET]
   - [x] Availabilities
     - https://www.doctolib.fr/availabilities.json?visit_motive_ids=7767829&agenda_ids=1101600&practice_ids=377272&telehealth=false&start_date=2026-03-06&limit=5
-  - Practitioner ? 
+  - [x] Practitioner
     - https://www.doctolib.fr/pharmacie/paris/pharmacie-faidherbe.json
     - https://www.doctolib.fr/dentiste/bordeaux/mathilde-devun-lesparre-medoc.json
     - https://www.doctolib.fr/a/b/mathilde-devun-lesparre-medoc.json
     - https://www.doctolib.fr/profiles/mathilde-devun-lesparre-medoc.json
-  - Rassemblement practiciens / Place Practitioners collection
+  - [x] Rassemblement practiciens / Place Practitioners collection
     - https://www.doctolib.fr/profiles/pavillon-de-la-mutualite-bordeaux-rue-vital-carles.json
-  - Places
+  - [ ] Places
     - https://www.doctolib.fr/patient_app/place_autocomplete.json?query=47300
-  - Booking context
+  - [x] Booking context
     - https://www.doctolib.fr/online_booking/api/slot_selection_funnel/v1/info.json?profile_slug=brigitte-devun-pujols&locale=fr
     - https://www.doctolib.fr/online_booking/api/slot_selection_funnel/v1/info.json?profile_slug=926388&locale=fr
 - Interesting NON JSONs

data/README.md

@@ -61,6 +61,16 @@ or install it directly:
 gem install toc_doc
 ```
 
+### Alternative: gem.coop
+
+If you prefer to install from [gem.coop](https://gem.coop), toc_doc is also [available there](https://beta.gem.coop/@maxime/toc_doc) :
+
+```ruby
+source 'https://gem.coop' do
+  gem 'toc_doc'
+end
+```
+
 ---
 
 ## Quick start
@@ -130,9 +140,11 @@ client.get('/availabilities.json', query: { visit_motive_ids: '123', agenda_ids:
 | Option | Default | Description |
 |---|---|---|
 | `api_endpoint` | `https://www.doctolib.fr` | Base URL. Change to `.de` / `.it` for other countries. |
-| `user_agent` | `TocDoc Ruby Gem 1.5.0` | `User-Agent` header sent with every request. |
+| `user_agent` | `TocDoc Ruby Gem 1.6.0` | `User-Agent` header sent with every request. |
 | `default_media_type` | `application/json` | `Accept` and `Content-Type` headers. |
-| `per_page` | `15` | Default number of availability dates per request (capped at `15`). |
+| `per_page` | `15` | Default number of availability dates per request (capped at `15`). Emits a warning if the value exceeds the cap. |
+| `connect_timeout` | `5` | TCP connect timeout in seconds, passed to Faraday as `open_timeout`. Override via `TOCDOC_CONNECT_TIMEOUT`. |
+| `read_timeout` | `10` | Response read timeout in seconds, passed to Faraday as `timeout`. Override via `TOCDOC_READ_TIMEOUT`. |
 | `middleware` | Retry + RaiseError + JSON + adapter | Full Faraday middleware stack. Override to customise completely. |
 | `connection_options` | `{}` | Options passed directly to `Faraday.new`. |
 
@@ -146,6 +158,8 @@ All primary options can be set via environment variables before the gem is loade
 | `TOCDOC_USER_AGENT` | `user_agent` |
 | `TOCDOC_MEDIA_TYPE` | `default_media_type` |
 | `TOCDOC_PER_PAGE` | `per_page` |
+| `TOCDOC_CONNECT_TIMEOUT` | `connect_timeout` (default `5`) |
+| `TOCDOC_READ_TIMEOUT` | `read_timeout` (default `10`) |
 | `TOCDOC_RETRY_MAX` | Maximum Faraday retry attempts (default `3`) |
 
 ---
@@ -474,8 +488,34 @@ rescue TocDoc::Error => e
 end
 ```
 
-The default middleware stack also includes `Faraday::Response::RaiseError` for
-HTTP-level failures, and a `Faraday::Retry::Middleware` that automatically
+### Error classes
+
+| Class | Raised when |
+|---|---|
+| `TocDoc::Error` | Base class for all TocDoc errors. |
+| `TocDoc::ConnectionError` | Network/transport failure before a response is received (DNS, timeout, SSL). The original cause is available via `#cause`. |
+| `TocDoc::ResponseError` | HTTP response received but indicates an error. Carries `#status`, `#body`, and `#headers`. |
+| `TocDoc::ClientError` | 4xx response not matched by a more specific class. |
+| `TocDoc::BadRequest` | HTTP 400. |
+| `TocDoc::NotFound` | HTTP 404. |
+| `TocDoc::UnprocessableEntity` | HTTP 422. |
+| `TocDoc::TooManyRequests` | HTTP 429. |
+| `TocDoc::ServerError` | 5xx response. |
+
+```ruby
+begin
+  TocDoc::Profile.find('unknown-slug')
+rescue TocDoc::NotFound => e
+  puts e.status    # => 404
+  puts e.body      # => '{"error":"not found"}'
+rescue TocDoc::ConnectionError => e
+  puts e.cause     # original Faraday exception
+rescue TocDoc::ServerError => e
+  puts "Server error: #{e.status}"
+end
+```
+
+The default middleware stack includes a `Faraday::Retry::Middleware` that automatically
 retries (up to 3 times, with exponential back-off) on:
 
 - `429 Too Many Requests`

data/TODO.md

@@ -2,26 +2,62 @@
 
 [POTENTIAL_ENDPOINTS][POTENTIAL_ENDPOINTS.md]
 
-## 1.6
 
-### Better API usage
-- [ ] Rate limiting
-- [ ] Caching
-- [ ] Logging
+## 1.7 — DevX
+
+- [ ] Logging middleware (`:logger` config key)
+- [ ] Resource: `define_singleton_method` on first access + `#attribute_names`
+- [ ] Deep `to_h` and `to_json` on `Resource` and `BookingInfo`
+- [ ] `Collection#filtered_entries` memoization
+- [ ] `BookingInfo#agendas` O(n*m) → hash lookup
+
+## 1.8 — HTTP Layer Robustness
+
+- [ ] Configurable availability pagination depth + `Collection#more?` / `#fetch_next_page`
+- [ ] Client-side rate limiter (token-bucket middleware)
+- [ ] Optional response caching (memory or ActiveSupport-compatible store)
+
+## 1.9 — Service Layer rework
+
+- [ ] `TocDoc::Services::Availabilities` — extract from `Availability.where`
+- [ ] `TocDoc::Services::Profiles` — extract from `Profile.find`
+- [ ] `TocDoc::Services::Search` — extract from `Search.where`
+- [ ] `TocDoc::Services::BookingInfos` — extract from `BookingInfo.find`
+- [ ] Update top-level shortcuts to delegate to services
+- [ ] Deprecation on old model-level finders
 
-## 2.0
+## 2.0 — Breaking Changes
 
-### Auth / User-based actions
-- [ ] Research auth scheme
-- [ ] Authentication module + headers
-- [ ] Auth specs
+- [ ] Remove deprecated model-level finders
+- [ ] `Place#coordinates` as `Data.define(:latitude, :longitude)`
+- [ ] Integration smoke test suite (gated by ENV, weekly CI cron)
+- [ ] Remove unused HTTP verbs from `Connection` (if auth doesn't ship)
 
 # ???
 
 - [ ] Figure what is `organization_statuses` in the autocomplete endpoint and what to do with it.
+- [ ] Authentication module
+- [ ] Place autocomplete endpoint ? (`/patient_app/place_autocomplete.json`)
 
 # DONE & RELEASED
 
+## 1.6
+
+### Default connection timeouts
+- [x] Add `CONNECT_TIMEOUT` and `READ_TIMEOUT` constants to `Default`
+- [x] Add config keys and ENV overrides (`TOCDOC_CONNECT_TIMEOUT`, `TOCDOC_READ_TIMEOUT`)
+- [x] Wire into `Connection#faraday_options`
+
+### Error hierarchy with HTTP context
+- [x] Build error subclass tree (`ConnectionError`, `ResponseError`, `ClientError`, `NotFound`, `TooManyRequests`, `ServerError`)
+- [x] Rewrite `RaiseError` middleware (`on_complete` pattern, status → subclass mapping)
+- [x] Remove `Faraday::Response::RaiseError` from middleware stack
+
+### Fixes
+- [x] Fix middleware memoization leak (`Default.reset!`)
+- [x] Warn on silent `per_page` clamping
+- [x] Remove dead code (`base_middleware.rb`, `retry_options_fallback` duplication)
+
 ## 1.5
 
 - [x] Booking context
@@ -102,4 +138,4 @@
   - [x] on rubygem
   - [x] release on GH
   - [x] gem.coop/@maxime
-- [x] Add test coverage tool
+- [x] Add test coverage tool

data/lib/toc_doc/core/configurable.rb

@@ -29,6 +29,8 @@ module TocDoc
       connection_options
       default_media_type
       per_page
+      connect_timeout
+      read_timeout
     ].freeze
 
     # @!attribute [rw] api_endpoint
@@ -41,15 +43,26 @@ module TocDoc
     #   @return [Hash] additional Faraday connection options
     # @!attribute [rw] default_media_type
     #   @return [String] the Accept / Content-Type header value
+    # @!attribute [rw] connect_timeout
+    #   @return [Integer] TCP connect timeout in seconds
+    # @!attribute [rw] read_timeout
+    #   @return [Integer] read (response) timeout in seconds
     attr_accessor(*VALID_CONFIG_KEYS)
 
     # Set the number of results per page, clamped to
     # {TocDoc::Default::MAX_PER_PAGE}.
     #
+    # Emits a warning on +$stderr+ when +value+ exceeds the hard cap so callers
+    # are not silently surprised by the lower effective value.
+    #
     # @param value [Integer, #to_i] desired page size
     # @return [Integer] the effective page size after clamping
     def per_page=(value)
-      @per_page = [value.to_i, TocDoc::Default::MAX_PER_PAGE].min
+      int = value.to_i
+      if int > TocDoc::Default::MAX_PER_PAGE
+        warn "[TocDoc] per_page #{int} exceeds MAX_PER_PAGE (#{TocDoc::Default::MAX_PER_PAGE}); clamped."
+      end
+      @per_page = [int, TocDoc::Default::MAX_PER_PAGE].min
     end
 
     # Returns the list of recognised configurable attribute names.
@@ -76,8 +89,13 @@ module TocDoc
 
     # Reset all configuration options to their {TocDoc::Default} values.
     #
+    # Calls {TocDoc::Default.reset!} first so that memoized values such as
+    # {TocDoc::Default.middleware} are cleared and rebuilt fresh on the next
+    # access, preventing stale middleware stacks from being reused.
+    #
     # @return [self]
     def reset!
+      TocDoc::Default.reset!
       TocDoc::Default.options.each do |key, value|
         public_send("#{key}=", value)
       end

data/lib/toc_doc/core/connection.rb

@@ -24,7 +24,7 @@ module TocDoc
 
     # Perform a GET request.
     #
-    # @param path [String] API path (relative to {Configurable#api_endpoint})
+    # @param path [String] API path (relative to {TocDoc::Configurable#api_endpoint})
     # @param options [Hash] query / header options forwarded to {#request}
     # @return [Object] parsed response body
     def get(path, options = {})
@@ -93,6 +93,7 @@ module TocDoc
     def faraday_options
       opts = connection_options.dup
       opts[:builder] = middleware if middleware
+      opts[:request] = { timeout: read_timeout, open_timeout: connect_timeout }
       opts
     end
 

data/lib/toc_doc/core/default.rb

@@ -31,6 +31,12 @@ module TocDoc
     # @return [Integer] the default maximum number of retries
     MAX_RETRY      = 3
 
+    # @return [Integer] the default TCP connect timeout in seconds
+    CONNECT_TIMEOUT = 5
+
+    # @return [Integer] the default read (response) timeout in seconds
+    READ_TIMEOUT    = 10
+
     class << self
       # Returns a hash of all default configuration values, suitable for
       # passing to {TocDoc::Configurable#reset!}.
@@ -43,7 +49,9 @@ module TocDoc
           default_media_type: default_media_type,
           per_page: per_page,
           middleware: middleware,
-          connection_options: connection_options
+          connection_options: connection_options,
+          connect_timeout: connect_timeout,
+          read_timeout: read_timeout
         }
       end
 
@@ -91,8 +99,9 @@ module TocDoc
 
       # The default Faraday middleware stack.
       #
-      # Includes retry logic, error raising, JSON parsing, and the default
-      # adapter.
+      # Stack order (outermost first): RaiseError, retry, JSON parsing, adapter.
+      # RaiseError is outermost so it wraps retry and maps the final response or
+      # re-raised transport exception into a typed {TocDoc::Error}.
       #
       # @return [Faraday::RackBuilder]
       def middleware
@@ -106,13 +115,48 @@ module TocDoc
         @connection_options ||= {}
       end
 
+      # The TCP connect timeout in seconds.
+      #
+      # Falls back to the `TOCDOC_CONNECT_TIMEOUT` environment variable, then
+      # {CONNECT_TIMEOUT}.  Invalid ENV values fall back to {CONNECT_TIMEOUT}.
+      #
+      # @return [Integer]
+      def connect_timeout
+        Integer(ENV.fetch('TOCDOC_CONNECT_TIMEOUT', CONNECT_TIMEOUT), 10)
+      rescue ArgumentError
+        CONNECT_TIMEOUT
+      end
+
+      # The read (response) timeout in seconds.
+      #
+      # Falls back to the `TOCDOC_READ_TIMEOUT` environment variable, then
+      # {READ_TIMEOUT}.  Invalid ENV values fall back to {READ_TIMEOUT}.
+      #
+      # @return [Integer]
+      def read_timeout
+        Integer(ENV.fetch('TOCDOC_READ_TIMEOUT', READ_TIMEOUT), 10)
+      rescue ArgumentError
+        READ_TIMEOUT
+      end
+
+      # Clears all memoized values so the next call to {.middleware} and
+      # {.connection_options} rebuilds them from scratch.
+      #
+      # Called by {TocDoc::Configurable#reset!} to ensure each reset produces a
+      # fresh middleware stack rather than reusing a stale memoized instance.
+      #
+      # @return [void]
+      def reset!
+        @middleware = nil
+        @connection_options = nil
+      end
+
       private
 
       def build_middleware
         Faraday::RackBuilder.new do |builder|
-          builder.request :retry, retry_options
           builder.use TocDoc::Middleware::RaiseError
-          builder.response :raise_error
+          builder.request :retry, retry_options
           builder.response :json, content_type: /\bjson$/
           builder.adapter Faraday.default_adapter
         end
@@ -120,26 +164,19 @@ module TocDoc
 
       def retry_options
         {
-          max: Integer(ENV.fetch('TOCDOC_RETRY_MAX', MAX_RETRY), 10),
+          max: retry_max,
           interval: 0.5,
           interval_randomness: 0.5,
           backoff_factor: 2,
           retry_statuses: [429, 500, 502, 503, 504],
           methods: %i[get head options]
         }
-      rescue ArgumentError
-        retry_options_fallback
       end
 
-      def retry_options_fallback
-        {
-          max: MAX_RETRY,
-          interval: 0.5,
-          interval_randomness: 0.5,
-          backoff_factor: 2,
-          retry_statuses: [429, 500, 502, 503, 504],
-          methods: %i[get head options]
-        }
+      def retry_max
+        Integer(ENV.fetch('TOCDOC_RETRY_MAX', MAX_RETRY), 10)
+      rescue ArgumentError
+        MAX_RETRY
       end
     end
   end

data/lib/toc_doc/core/error.rb

@@ -3,7 +3,7 @@
 module TocDoc
   # Base error class for all TocDoc errors.
   #
-  # Inherits from +StandardError+ so consumers can rescue `TocDoc::Error`
+  # Inherits from +StandardError+ so consumers can rescue +TocDoc::Error+
   # without any knowledge of Faraday or other internal HTTP details.
   #
   # @example Rescuing TocDoc errors
@@ -13,4 +13,78 @@ module TocDoc
   #     puts e.message
   #   end
   class Error < StandardError; end
+
+  # Raised when a network-level failure occurs before an HTTP response is
+  # received (e.g. DNS resolution failure, connection refused, timeout).
+  #
+  # The original low-level exception is available via Ruby's built-in
+  # +#cause+ mechanism — no extra attribute needed.
+  #
+  # @example
+  #   rescue TocDoc::ConnectionError => e
+  #     puts e.cause  # original Faraday::ConnectionFailed, etc.
+  class ConnectionError < Error; end
+
+  # Raised when an HTTP response is received but indicates an error.
+  #
+  # Carries the raw response details so callers can act on them without
+  # needing to reach into Faraday internals.
+  #
+  # @example
+  #   rescue TocDoc::ResponseError => e
+  #     puts e.status   # => 404
+  #     puts e.body     # => '{"error":"not found"}'
+  #     puts e.headers  # => {"content-type"=>"application/json"}
+  class ResponseError < Error
+    # @return [Integer] the HTTP status code
+    attr_reader :status
+
+    # @return [String, nil] the raw response body
+    attr_reader :body
+
+    # @return [Hash, nil] the response headers
+    attr_reader :headers
+
+    # @param status [Integer] the HTTP status code
+    # @param body [String, nil] the raw response body
+    # @param headers [Hash, nil] the response headers
+    # @param message [String, nil] optional override for the error message;
+    #   defaults to +"HTTP #{status}"+
+    def initialize(status:, body: nil, headers: nil, message: nil)
+      @status = status
+      @body = body
+      @headers = headers
+      super(message || "HTTP #{status}")
+    end
+  end
+
+  # Raised for 4xx client error responses.
+  #
+  # @see ResponseError
+  class ClientError < ResponseError; end
+
+  # Raised for HTTP 400 Bad Request responses.
+  #
+  # @see ClientError
+  class BadRequest < ClientError; end
+
+  # Raised for HTTP 404 Not Found responses.
+  #
+  # @see ClientError
+  class NotFound < ClientError; end
+
+  # Raised for HTTP 422 Unprocessable Entity responses.
+  #
+  # @see ClientError
+  class UnprocessableEntity < ClientError; end
+
+  # Raised for HTTP 429 Too Many Requests responses.
+  #
+  # @see ClientError
+  class TooManyRequests < ClientError; end
+
+  # Raised for 5xx server error responses.
+  #
+  # @see ResponseError
+  class ServerError < ResponseError; end
 end

data/lib/toc_doc/core/version.rb

@@ -4,5 +4,5 @@ module TocDoc
   # The current version of the TocDoc gem.
   #
   # @return [String]
-  VERSION = '1.5.0'
+  VERSION = '1.6.0'
 end

data/lib/toc_doc/http/middleware/raise_error.rb

@@ -4,24 +4,81 @@ require 'faraday'
 
 module TocDoc
   # @api private
+  # Namespace for Faraday middleware used internally by {TocDoc}.
   module Middleware
-    # Faraday middleware that translates Faraday HTTP errors into
-    # {TocDoc::Error}, keeping Faraday as an internal implementation detail.
+    # Faraday middleware that translates HTTP error responses and transport-level
+    # failures into typed {TocDoc::Error} subclasses, keeping Faraday as an
+    # internal implementation detail.
     #
-    # Registered in the default middleware stack built by {TocDoc::Default}.
+    # Placed as the outermost middleware so the retry middleware operates on raw
+    # Faraday exceptions and returns the final response after exhaustion.
+    #
+    # Two-pronged error mapping:
+    # - +on_complete+: inspects the HTTP status and raises the appropriate
+    #   {TocDoc::ResponseError} subclass for 4xx/5xx responses.
+    # - +rescue+ in +call+: catches Faraday transport errors and raises
+    #   {TocDoc::ConnectionError}.
     #
     # @see TocDoc::Error
+    # @see TocDoc::ConnectionError
+    # @see TocDoc::ResponseError
     class RaiseError < Faraday::Middleware
-      # Executes the request and re-raises any +Faraday::Error+ as a
-      # {TocDoc::Error}.
+      # Maps specific HTTP status codes to their typed error classes.
+      # Statuses not in this map fall back to {TocDoc::ClientError} (4xx) or
+      # {TocDoc::ServerError} (5xx).
+      #
+      # @return [Hash{Integer => Class}]
+      STATUS_MAP = {
+        400 => TocDoc::BadRequest,
+        404 => TocDoc::NotFound,
+        422 => TocDoc::UnprocessableEntity,
+        429 => TocDoc::TooManyRequests
+      }.freeze
+
+      # Executes the request, raises {TocDoc::ConnectionError} on transport
+      # failures, and delegates HTTP error mapping to +on_complete+.
       #
       # @param env [Faraday::Env] the Faraday request environment
-      # @return [Faraday::Env] the response environment on success
-      # @raise [TocDoc::Error] when Faraday raises an HTTP error
+      # @return [Faraday::Response] the response on success
+      # @raise [TocDoc::ConnectionError] on network/transport-level failures
+      # @raise [TocDoc::ResponseError] on 4xx or 5xx HTTP responses
       def call(env)
-        @app.call(env)
-      rescue Faraday::Error => e
-        raise TocDoc::Error, e.message
+        @app.call(env).on_complete do |response_env|
+          on_complete(response_env)
+        end
+      rescue Faraday::TimeoutError, Faraday::ConnectionFailed, Faraday::SSLError => e
+        raise TocDoc::ConnectionError, e.message
+      end
+
+      private
+
+      # Maps the HTTP status in +env+ to a typed {TocDoc::ResponseError} and
+      # raises it. No-ops for non-error statuses.
+      #
+      # @param env [Faraday::Env] the completed response environment
+      # @return [void]
+      # @raise [TocDoc::ResponseError] for 4xx or 5xx status codes
+      def on_complete(env)
+        status  = env[:status]
+        body    = env[:body]
+        headers = env[:response_headers]
+
+        error_class = error_class_for(status)
+        raise error_class.new(status: status, body: body, headers: headers) if error_class
+      end
+
+      # Resolves the error class for a given HTTP status code.
+      #
+      # @param status [Integer] the HTTP status code
+      # @return [Class, nil] the error class, or +nil+ if the status is not an error
+      def error_class_for(status)
+        if STATUS_MAP.key?(status)
+          STATUS_MAP[status]
+        elsif status >= 400 && status < 500
+          TocDoc::ClientError
+        elsif status >= 500
+          TocDoc::ServerError
+        end
       end
     end
   end

data/lib/toc_doc/models/availability.rb

@@ -17,6 +17,8 @@ module TocDoc
 
     attr_reader :date, :slots
 
+    # API path for the availabilities endpoint.
+    # @return [String]
     PATH = '/availabilities.json'
 
     class << self

data/lib/toc_doc/models/booking_info.rb

@@ -22,6 +22,8 @@ module TocDoc
   #   info.visit_motives  #=> [#<TocDoc::VisitMotive>, ...]
   #   info.organization?  #=> false
   class BookingInfo
+    # API path for the slot-selection funnel info endpoint.
+    # @return [String]
     PATH = '/online_booking/api/slot_selection_funnel/v1/info.json'
 
     class << self

data/lib/toc_doc/models/place.rb

@@ -27,6 +27,12 @@ module TocDoc
   #   place.latitude         #=> 44.8386722
   #   place.elevator         #=> true
   class Place < Resource
+    # Returns the geographic coordinates of the place.
+    #
+    # @return [Array(Float, Float)] +[latitude, longitude]+
+    #
+    # @example
+    #   place.coordinates  #=> [44.8386722, -0.5780466]
     def coordinates
       [latitude, longitude]
     end

data/lib/toc_doc/models/profile/practitioner.rb

@@ -6,6 +6,12 @@ module TocDoc
     class Practitioner < Profile
       main_attrs :name_with_title
 
+      # Returns the practitioner's display name.
+      #
+      # Prefers +name_with_title+ (e.g. "Dr Jane Doe") when present,
+      # falling back to plain +name+.
+      #
+      # @return [String]
       def to_s
         (respond_to?(:name_with_title) && name_with_title) || name
       end

data/lib/toc_doc/models/profile.rb

@@ -12,6 +12,8 @@ module TocDoc
   #   profile.practitioner?  #=> true
   #   profile.name           #=> "Dr Smith"
   class Profile < Resource
+    # API path template for a full profile page (+sprintf+-style, requires +identifier+).
+    # @return [String]
     PATH = '/profiles/%<identifier>s.json'
 
     main_attrs :id, :partial

data/lib/toc_doc/models/search.rb

@@ -17,7 +17,12 @@ module TocDoc
   #   TocDoc::Search.where(query: 'dentiste', type: 'practitioner')
   #   #=> [#<TocDoc::Profile::Practitioner>, ...]
   class Search
+    # API path for the autocomplete / searchbar endpoint.
+    # @return [String]
     PATH = '/api/searchbar/autocomplete.json'
+
+    # Accepted values for the +type:+ keyword in {.where}.
+    # @return [Array<String>]
     VALID_TYPES = %w[profile practitioner organization speciality].freeze
 
     class << self

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toc_doc
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - 01max
@@ -71,7 +71,6 @@ files:
 - lib/toc_doc/core/uri_utils.rb
 - lib/toc_doc/core/version.rb
 - lib/toc_doc/http/middleware/raise_error.rb
-- lib/toc_doc/http/response/base_middleware.rb
 - lib/toc_doc/middleware/.keep
 - lib/toc_doc/models.rb
 - lib/toc_doc/models/agenda.rb

data/lib/toc_doc/http/response/base_middleware.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-require 'faraday'
-
-module TocDoc
-  # @api private
-  module Response
-    # Abstract base class for TocDoc Faraday response middleware.
-    #
-    # Subclasses **must** override {#on_complete} to inspect or transform
-    # the response environment.
-    #
-    # @abstract
-    class BaseMiddleware < Faraday::Middleware
-      # Called by Faraday after the response has been received.
-      #
-      # @param env [Faraday::Env] the Faraday response environment
-      # @return [void]
-      # @raise [NotImplementedError] always — subclasses must override
-      def on_complete(env)
-        raise NotImplementedError, "#{self.class} must implement #on_complete"
-      end
-    end
-  end
-end