toc_doc 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97e03e2d5bbc3fffa25a74e1dc6367d27befc2c25009889ff55b25c2f0abad46
-  data.tar.gz: 847c1832c1a927024404004c11c3adb966142d6e93df3de2692d9734f400b2d2
+  metadata.gz: 50818c97b021143ebf2d502a867fb5f20a90299a822ec800b7d02ae4d20999eb
+  data.tar.gz: d4ef919a143957c2685fba1f28675786743922387b0703c521a6d5c0b9ab76c3
 SHA512:
-  metadata.gz: fe6ff537f03f02a3ecc17013558bcbe165667cc2bb1275d9cea12f28e84457672b278bdfc7f6e00a7f894be7ce5f3587bf02f70d2f6e5f7f70c0c2109372a145
-  data.tar.gz: c710d06fb3b1137c1ff2bc4a5f8c9a79c527c7c8e777d99bffd4f11f6799ae4c8dad188a558ac6f29a4696bde45eeb70ffb62b396a2e17cc6805005cf381cb41
+  metadata.gz: 9aa3dd68984a7cec38789a3a718db4f7c9db9a0335ae8e47744f24990dccb73de12e41903aee8806e06f579288769c13a5b9f82327a031dd3c2052d096ae33e5
+  data.tar.gz: 10725265d2117c4d93720c89f5c06360ea567377c6d21f9a848e26151de7039876ac9a7b1da936801f0eaf9a7b8141689e8389b5a2917f3d550a01847aa52767

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 ## [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
+
+- **`TocDoc::BookingInfo`** — new envelope class for the slot-selection funnel info endpoint (`/online_booking/api/slot_selection_funnel/v1/info.json`); `BookingInfo.find(identifier)` fetches booking context by profile slug or numeric ID and returns a typed `BookingInfo` instance
+- **`TocDoc::BookingInfo#profile`** — returns the typed profile (`Practitioner` or `Organization`) via `Profile.build`
+- **`TocDoc::BookingInfo#specialities`** — returns an array of `TocDoc::Speciality` objects
+- **`TocDoc::BookingInfo#visit_motives`** — returns an array of `TocDoc::VisitMotive` objects
+- **`TocDoc::BookingInfo#agendas`** — returns an array of `TocDoc::Agenda` objects, each pre-resolved with its matching `VisitMotive` objects via `visit_motive_ids`
+- **`TocDoc::BookingInfo#places`** — returns an array of `TocDoc::Place` objects
+- **`TocDoc::BookingInfo#practitioners`** — returns an array of `TocDoc::Profile::Practitioner` objects (marked `partial: true`)
+- **`TocDoc::BookingInfo#organization?`** — delegates to the inner profile
+- **`TocDoc::VisitMotive`** — new `Resource`-based model representing a visit motive (reason for consultation); exposes `#id` and `#name` via dot-notation
+- **`TocDoc::Agenda`** — new `Resource`-based model representing an agenda (calendar); exposes `#id` and `#practice_id` via dot-notation; supports pre-resolved `#visit_motives` when built through `BookingInfo`
+- **`TocDoc.booking_info`** — top-level shortcut delegating to `TocDoc::BookingInfo.find`
+
 ## [1.4.0] - 2026-03-19
 
 ### 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

@@ -29,6 +29,7 @@ A Ruby gem for interacting with the (unofficial) Doctolib API. A thin, Faraday-b
    - [Availabilities](#availabilities)
    - [Search](#search)
    - [Profile](#profile)
+   - [BookingInfo](#bookinginfo)
 5. [Response objects](#response-objects)
 6. [Pagination](#pagination)
 7. [Error handling](#error-handling)
@@ -60,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
@@ -129,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.4.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`. |
 
@@ -145,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`) |
 
 ---
@@ -241,6 +256,35 @@ profile.places.first.coordinates       # => [44.8386722, -0.5780466]
 
 **Return value:** a `TocDoc::Profile::Practitioner` or `TocDoc::Profile::Organization` (see [Response objects](#response-objects)).
 
+### BookingInfo
+
+Fetch the slot-selection funnel context for a practitioner or organization by slug or numeric ID.
+
+```ruby
+# by slug
+info = TocDoc::BookingInfo.find('jane-doe-bordeaux')
+
+# by numeric ID
+info = TocDoc::BookingInfo.find(1_542_899)
+
+# module-level shortcut
+info = TocDoc.booking_info('jane-doe-bordeaux')
+```
+
+`BookingInfo.find` hits `/online_booking/api/slot_selection_funnel/v1/info.json` and returns a `TocDoc::BookingInfo` instance containing the full booking context needed to drive the appointment-booking funnel.
+
+```ruby
+info.profile        # => #<TocDoc::Profile::Practitioner ...>
+info.specialities   # => [#<TocDoc::Speciality ...>, ...]
+info.visit_motives  # => [#<TocDoc::VisitMotive id=..., name="...">, ...]
+info.agendas        # => [#<TocDoc::Agenda id=..., practice_id=...>, ...]
+info.places         # => [#<TocDoc::Place ...>, ...]
+info.practitioners  # => [#<TocDoc::Profile::Practitioner partial=true>, ...]
+info.organization?  # => false
+```
+
+**Return value:** a `TocDoc::BookingInfo` (see [Response objects](#response-objects)).
+
 ---
 
 ## Response objects
@@ -337,6 +381,39 @@ Represents a practice location returned inside a full profile response. Inherits
 | `#formal_name` | `String \| nil` | Formal practice name, if available. |
 | `#coordinates` | `Array<Float>` | Convenience method returning `[latitude, longitude]`. |
 
+### `TocDoc::BookingInfo`
+
+Returned by `TocDoc::BookingInfo.find`; also accessible via the `TocDoc.booking_info` module-level shortcut.
+
+| Method | Type | Description |
+|---|---|---|
+| `#profile` | `Profile::Practitioner \| Profile::Organization` | Typed profile built via `Profile.build`. |
+| `#specialities` | `Array<TocDoc::Speciality>` | Specialities associated with the booking context. |
+| `#visit_motives` | `Array<TocDoc::VisitMotive>` | Available visit motives (reasons for consultation). |
+| `#agendas` | `Array<TocDoc::Agenda>` | Agendas, each pre-resolved with their matching `VisitMotive` objects. |
+| `#places` | `Array<TocDoc::Place>` | Practice locations. |
+| `#practitioners` | `Array<TocDoc::Profile::Practitioner>` | Practitioners associated with this booking context (`partial: true`). |
+| `#organization?` | `Boolean` | Delegates to the inner profile. |
+
+### `TocDoc::VisitMotive`
+
+Represents a visit motive (reason for consultation) returned inside a `BookingInfo` response. Inherits dot-notation attribute access from `TocDoc::Resource`.
+
+| Method | Type | Description |
+|---|---|---|
+| `#id` | `Integer` | Visit motive identifier. |
+| `#name` | `String` | Human-readable name of the visit motive. |
+
+### `TocDoc::Agenda`
+
+Represents an agenda (calendar) returned inside a `BookingInfo` response. Inherits dot-notation attribute access from `TocDoc::Resource`.
+
+| Method | Type | Description |
+|---|---|---|
+| `#id` | `Integer` | Agenda identifier. |
+| `#practice_id` | `Integer` | ID of the associated practice. |
+| `#visit_motives` | `Array<TocDoc::VisitMotive>` | Visit motives pre-resolved via `visit_motive_ids` when built through `BookingInfo`. |
+
 ### `TocDoc::Speciality`
 
 Represents a speciality returned by the autocomplete endpoint. Inherits dot-notation attribute access from `TocDoc::Resource`.
@@ -411,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,31 +2,68 @@
 
 [POTENTIAL_ENDPOINTS][POTENTIAL_ENDPOINTS.md]
 
-## 1.5
 
-- [ ] Booking context
-  - https://www.doctolib.fr/online_booking/api/slot_selection_funnel/v1/info.json?profile_slug=926388
+## 1.7 — DevX
 
-## 1.6
+- [ ] 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)
 
-### Better API usage
-- [ ] Rate limiting
-- [ ] Caching
-- [ ] Logging
+## 1.9 — Service Layer rework
 
-## 2.0
+- [ ] `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
 
-### Auth / User-based actions
-- [ ] Research auth scheme
-- [ ] Authentication module + headers
-- [ ] Auth specs
+## 2.0 — Breaking Changes
+
+- [ ] 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
+  - practitioner : https://www.doctolib.fr/online_booking/api/slot_selection_funnel/v1/info.json?profile_slug=926388
+  - organization : https://www.doctolib.fr/online_booking/api/slot_selection_funnel/v1/info.json?profile_slug=325629
+
 ## 1.4
 
 - [x] Profile
@@ -101,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.4.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/agenda.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TocDoc
+  # Represents an agenda (calendar) returned by the booking info endpoint.
+  #
+  # The +id+ and +practice_id+ fields are the primary attributes. Additional
+  # fields such as +visit_motive_ids+ and +visit_motive_ids_by_practice_id+ are
+  # accessible via dot-notation inherited from {TocDoc::Resource}.
+  #
+  # @example
+  #   agenda = TocDoc::Agenda.new(
+  #     'id'          => 42,
+  #     'practice_id' => 'practice-125055',
+  #     'visit_motive_ids' => [1, 2]
+  #   )
+  #   agenda.id           #=> 42
+  #   agenda.practice_id  #=> "practice-125055"
+  class Agenda < Resource
+    main_attrs :id, :practice_id
+  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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require 'toc_doc/models/profile'
+require 'toc_doc/models/speciality'
+require 'toc_doc/models/place'
+require 'toc_doc/models/visit_motive'
+require 'toc_doc/models/agenda'
+
+module TocDoc
+  # Envelope returned by the slot-selection funnel info endpoint.
+  #
+  # Wraps the raw API response and exposes typed collections for the booking
+  # context: profile, specialities, visit motives, agendas, places, and
+  # practitioners.
+  #
+  # Unlike {TocDoc::Profile}, this class is NOT a {Resource} subclass — it is
+  # a plain envelope class, similar in role to {TocDoc::Search::Result}.
+  #
+  # @example
+  #   info = TocDoc::BookingInfo.find('jane-doe-bordeaux')
+  #   info.profile        #=> #<TocDoc::Profile::Practitioner>
+  #   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
+      # Fetches booking info for a profile slug or numeric ID.
+      #
+      # @param identifier [String, Integer] profile slug or numeric ID,
+      #   forwarded as the +profile_slug+ query parameter
+      # @return [BookingInfo]
+      # @raise [ArgumentError] if +identifier+ is +nil+
+      #
+      # @example
+      #   TocDoc::BookingInfo.find('jane-doe-bordeaux')
+      #   TocDoc::BookingInfo.find(325629)
+      def find(identifier)
+        raise ArgumentError, 'identifier cannot be nil' if identifier.nil?
+
+        data = TocDoc.client.get(PATH, query: { profile_slug: identifier })['data']
+        new(data)
+      end
+    end
+
+    # @param data [Hash] the +data+ value from the API response body
+    def initialize(data)
+      @data = data
+    end
+
+    # The profile associated with this booking context, typed via
+    # {TocDoc::Profile.build}.
+    #
+    # @return [TocDoc::Profile::Practitioner, TocDoc::Profile::Organization]
+    def profile
+      @profile ||= Profile.build(@data['profile'])
+    end
+
+    # All specialities for this booking context.
+    #
+    # @return [Array<TocDoc::Speciality>]
+    def specialities
+      @specialities ||= Array(@data['specialities']).map do |speciality_attrs|
+        Speciality.new(speciality_attrs)
+      end
+    end
+
+    # All visit motives for this booking context.
+    #
+    # @return [Array<TocDoc::VisitMotive>]
+    def visit_motives
+      @visit_motives ||= Array(@data['visit_motives']).map do |visit_motive_attrs|
+        VisitMotive.new(visit_motive_attrs)
+      end
+    end
+
+    # All agendas for this booking context.
+    #
+    # @return [Array<TocDoc::Agenda>]
+    def agendas
+      @agendas ||= Array(@data['agendas']).map do |agenda_attrs|
+        agenda_visit_motives = visit_motives.select do |vm|
+          agenda_attrs['visit_motive_ids'].include?(vm.id)
+        end
+
+        Agenda.new(agenda_attrs.merge('visit_motives' => agenda_visit_motives))
+      end
+    end
+
+    # All practice locations for this booking context.
+    #
+    # @return [Array<TocDoc::Place>]
+    def places
+      @places ||= Array(@data['places']).map do |place_attrs|
+        Place.new(place_attrs)
+      end
+    end
+
+    # All practitioners associated with this booking context.
+    #
+    # Always constructed as {TocDoc::Profile::Practitioner} since the
+    # +practitioners+ array in this endpoint exclusively contains practitioners.
+    # Marked as partial since the data is a summary, not a full profile page.
+    #
+    # @return [Array<TocDoc::Profile::Practitioner>]
+    def practitioners
+      @practitioners ||= Array(@data['practitioners']).map do |practitioner_attrs|
+        Profile::Practitioner.new(practitioner_attrs.merge('partial' => true))
+      end
+    end
+
+    # Returns +true+ when the top-level profile is an organization.
+    #
+    # Delegates to {TocDoc::Profile#organization?}.
+    #
+    # @return [Boolean]
+    def organization?
+      profile.organization?
+    end
+
+    # Returns the raw data hash.
+    #
+    # @return [Hash]
+    def to_h
+      @data
+    end
+  end
+end

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,8 +6,14 @@ 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
-        name_with_title || name
+        (respond_to?(:name_with_title) && name_with_title) || name
       end
     end
   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
@@ -19,20 +21,26 @@ module TocDoc
     class << self
       # Factory — returns a +Profile::Practitioner+ or +Profile::Organization+.
       #
-      # Resolves type via +owner_type+ first (search context), then falls back
+      # Resolves type via +owner_type+ first (autocomplete context), then falls back
       # to the boolean flags present on profile-page responses.
       #
       # @param attrs [Hash] raw attribute hash from the API response
       # @return [Profile::Practitioner, Profile::Organization]
+      # @raise [ArgumentError] if +attrs+ contains an unknown +owner_type+ or the
+      #   profile type cannot be determined from the available flags
+      #
+      # @example Build from an autocomplete result
+      #   TocDoc::Profile.build('owner_type' => 'Account', 'name' => 'Dr Smith')
+      # @example Build from a full profile response
+      #   TocDoc::Profile.build('is_practitioner' => true, 'name' => 'Dr Smith')
       def build(attrs = {})
         attrs = normalize_attrs(attrs)
-        return find(attrs['value']) if attrs['force_full_profile'] && attrs['owner_type']
 
-        case attrs['owner_type']
-        when 'Account'      then Practitioner.new(attrs.merge('partial' => true))
-        when 'Organization' then Organization.new(attrs.merge('partial' => true))
-        else                     build_from_flags(attrs)
-        end
+        return find(attrs['value']) if attrs['force_full_profile']
+
+        build_from_autocomplete(attrs) ||
+          build_from_booking_info(attrs) ||
+          build_from_full_profile(attrs)
       end
 
       # Fetches a full profile page by slug or numeric ID.
@@ -53,7 +61,31 @@ module TocDoc
 
       private
 
-      def build_from_flags(attrs)
+      # Autocomplete results carry an +owner_type+ key that tells us the
+      # profile type directly.  When +force_full_profile+ is set, fetches
+      # the full profile page instead of building a partial.
+      #
+      # @param attrs [Hash] normalized attribute hash
+      # @return [Profile::Practitioner, Profile::Organization, nil] +nil+ when
+      #   +owner_type+ is absent
+      # @raise [ArgumentError] if +owner_type+ is present but unrecognised
+      def build_from_autocomplete(attrs)
+        return unless attrs['owner_type']
+
+        case attrs['owner_type']
+        when 'Account'      then Practitioner.new(attrs.merge('partial' => true))
+        when 'Organization' then Organization.new(attrs.merge('partial' => true))
+        else                     raise ArgumentError, "Unknown owner_type: #{attrs['owner_type']}"
+        end
+      end
+
+      # Builds a profile from a full profile-page response.
+      #
+      # @param attrs [Hash] normalized attribute hash from a full profile page
+      # @return [Profile::Practitioner, Profile::Organization]
+      # @raise [ArgumentError] if neither +is_practitioner+ nor +organization+
+      #   flag is present in +attrs+
+      def build_from_full_profile(attrs)
         if attrs['is_practitioner']
           Practitioner.new(attrs.merge('partial' => false))
         elsif attrs['organization']
@@ -63,6 +95,26 @@ module TocDoc
         end
       end
 
+      # Booking-info profiles carry `organization` (true/false) but lack
+      # `is_practitioner`.  Returns nil when the shape doesn't match so the
+      # caller can fall through to build_from_full_profile.
+      #
+      # @param attrs [Hash] normalized attribute hash
+      # @return [Profile::Practitioner, Profile::Organization, nil] +nil+ when
+      #   the booking-info shape is not matched
+      def build_from_booking_info(attrs)
+        return unless attrs.key?('organization') && !attrs.key?('is_practitioner')
+
+        return Organization.new(attrs.merge('partial' => true)) if attrs['organization']
+
+        Practitioner.new(attrs.merge('partial' => true))
+      end
+
+      # Extracts and coerces profile attributes from the raw API response.
+      #
+      # @param data [Hash] the +data+ key from the API response body
+      # @return [Hash] merged attribute hash with +speciality+ and +places+
+      #   coerced into model objects
       def profile_attrs(data)
         data['profile'].merge(
           'speciality' => TocDoc::Speciality.new(data['profile']['speciality'] || {}),
@@ -78,6 +130,9 @@ module TocDoc
     # Returns all skills across all practices as an array of {TocDoc::Resource}.
     #
     # @return [Array<TocDoc::Resource>]
+    #
+    # @example
+    #   profile.skills  #=> [#<TocDoc::Resource ...>, ...]
     def skills
       hash = self['skills_by_practice'] || {}
       hash.values.flatten.map { |s| TocDoc::Resource.new(s) }
@@ -87,17 +142,26 @@ module TocDoc
     #
     # @param practice_id [Integer, String] the practice ID
     # @return [Array<TocDoc::Resource>]
+    #
+    # @example
+    #   profile.skills_for(123)  #=> [#<TocDoc::Resource ...>, ...]
     def skills_for(practice_id)
       hash = self['skills_by_practice'] || {}
       Array(hash[practice_id.to_s]).map { |s| TocDoc::Resource.new(s) }
     end
 
     # @return [Boolean] true when this profile is a practitioner
+    #
+    # @example
+    #   profile.practitioner?  #=> true
     def practitioner?
       is_a?(Practitioner)
     end
 
     # @return [Boolean] true when this profile is an organization
+    #
+    # @example
+    #   profile.organization?  #=> false
     def organization?
       is_a?(Organization)
     end

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

data/lib/toc_doc/models/visit_motive.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module TocDoc
+  # Represents a visit motive (reason for consultation) returned by the booking
+  # info endpoint.
+  #
+  # The +id+ and +name+ fields are the primary attributes. Additional fields
+  # such as +restrictions+ are accessible via dot-notation inherited from
+  # {TocDoc::Resource}.
+  #
+  # @example
+  #   motive = TocDoc::VisitMotive.new('id' => 1, 'name' => 'Consultation', 'restrictions' => [])
+  #   motive.id    #=> 1
+  #   motive.name  #=> "Consultation"
+  class VisitMotive < Resource
+    main_attrs :id, :name
+  end
+end

data/lib/toc_doc/models.rb

@@ -3,6 +3,9 @@
 require 'toc_doc/models/resource'
 require 'toc_doc/models/speciality'
 require 'toc_doc/models/place'
+require 'toc_doc/models/visit_motive'
+require 'toc_doc/models/agenda'
+require 'toc_doc/models/booking_info'
 require 'toc_doc/models/search'
 
 require 'toc_doc/models/availability'

data/lib/toc_doc.rb

@@ -100,6 +100,17 @@ module TocDoc
       TocDoc::Profile.find(identifier)
     end
 
+    # Fetches booking context data for a profile by slug or numeric ID.
+    #
+    # Delegates to {TocDoc::BookingInfo.find} — see that method for full
+    # parameter documentation.
+    #
+    # @param identifier [String, Integer] profile slug or numeric ID
+    # @return [TocDoc::BookingInfo]
+    def booking_info(identifier)
+      TocDoc::BookingInfo.find(identifier)
+    end
+
     # @!visibility private
     def method_missing(method_name, ...)
       if client.respond_to?(method_name)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: toc_doc
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - 01max
@@ -71,11 +71,12 @@ 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
 - lib/toc_doc/models/availability.rb
 - lib/toc_doc/models/availability/collection.rb
+- lib/toc_doc/models/booking_info.rb
 - lib/toc_doc/models/place.rb
 - lib/toc_doc/models/profile.rb
 - lib/toc_doc/models/profile/organization.rb
@@ -84,6 +85,7 @@ files:
 - lib/toc_doc/models/search.rb
 - lib/toc_doc/models/search/result.rb
 - lib/toc_doc/models/speciality.rb
+- lib/toc_doc/models/visit_motive.rb
 - sig/toc_doc.rbs
 homepage: https://github.com/01max/toc_doc
 licenses:

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