toc_doc 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97e03e2d5bbc3fffa25a74e1dc6367d27befc2c25009889ff55b25c2f0abad46
-  data.tar.gz: 847c1832c1a927024404004c11c3adb966142d6e93df3de2692d9734f400b2d2
+  metadata.gz: beef9501f028dfc80d31fb212f9ff876b20b952801ce7712702144bfa572fb32
+  data.tar.gz: ade0bafa23b88557931944c4199e64b9f45c972814d5b7af4b6b343602ae32eb
 SHA512:
-  metadata.gz: fe6ff537f03f02a3ecc17013558bcbe165667cc2bb1275d9cea12f28e84457672b278bdfc7f6e00a7f894be7ce5f3587bf02f70d2f6e5f7f70c0c2109372a145
-  data.tar.gz: c710d06fb3b1137c1ff2bc4a5f8c9a79c527c7c8e777d99bffd4f11f6799ae4c8dad188a558ac6f29a4696bde45eeb70ffb62b396a2e17cc6805005cf381cb41
+  metadata.gz: 5fcf8a1d6b3e3ef1e200bbd34c91922859f1c31ebb1ed208c6810d75470e56a63030c1f325f2ec9c39bbb54a73b97f831b5503d26528e34f62863f8a63cbedda
+  data.tar.gz: 20b38a89845bdf86a3b6effae5f47fbfc97e1d461b309a95a0c1a5b072bce2e9b6c58ee627719a07b02751b93e0edcfb309e552d6c6516998c3e34a8fb1ab2ef

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [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/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)
@@ -129,7 +130,7 @@ 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.5.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`). |
 | `middleware` | Retry + RaiseError + JSON + adapter | Full Faraday middleware stack. Override to customise completely. |
@@ -241,6 +242,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 +367,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`.

data/TODO.md

@@ -2,11 +2,6 @@
 
 [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.6
 
 ### Better API usage
@@ -27,6 +22,12 @@
 
 # DONE & RELEASED
 
+## 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

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.5.0'
 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/booking_info.rb

@@ -0,0 +1,128 @@
+# 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
+    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/profile/practitioner.rb

@@ -7,7 +7,7 @@ module TocDoc
       main_attrs :name_with_title
 
       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

@@ -19,20 +19,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 +59,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 +93,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 +128,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 +140,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/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.5.0
 platform: ruby
 authors:
 - 01max
@@ -74,8 +74,10 @@ files:
 - 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 +86,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: