toc_doc 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6c39bc2d41f1be6ae2b12b23074de967614fc1c6067d217316c7cb8bb9f0c31
-  data.tar.gz: 6c3a8732a25916bb75ebb18c7f53a79ff272a0c8b646477160a8381890404dcf
+  metadata.gz: beef9501f028dfc80d31fb212f9ff876b20b952801ce7712702144bfa572fb32
+  data.tar.gz: ade0bafa23b88557931944c4199e64b9f45c972814d5b7af4b6b343602ae32eb
 SHA512:
-  metadata.gz: dde234124b736d0149ac1f45bb6ab654487fb4e0c91bffb6c1b2462f51fa50a94cb59c5e9d4c4c5ef688eb12b9a8f8f321a0b5384b7d4bebe375506f81001b87
-  data.tar.gz: 1fd5632c3e5c73f89ae8db6f844269d5674141332ea9fd1956691695c3ae7242a7d7f706b3b0742f361df6b7a6a8ed931dc25f6d4b2c01426c6cc0ee379dacde
+  metadata.gz: 5fcf8a1d6b3e3ef1e200bbd34c91922859f1c31ebb1ed208c6810d75470e56a63030c1f325f2ec9c39bbb54a73b97f831b5503d26528e34f62863f8a63cbedda
+  data.tar.gz: 20b38a89845bdf86a3b6effae5f47fbfc97e1d461b309a95a0c1a5b072bce2e9b6c58ee627719a07b02751b93e0edcfb309e552d6c6516998c3e34a8fb1ab2ef

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 ## [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
+
+- **`TocDoc::Place`** — new `Resource`-based model representing a practice location inside a profile response; exposes address/geo fields (`#address`, `#zipcode`, `#city`, `#full_address`, `#landline_number`, `#latitude`, `#longitude`, `#elevator`, `#handicap`, `#formal_name`) via dot-notation and adds `#coordinates` returning `[latitude, longitude]`
+- **`TocDoc::Profile.find`** — class method that fetches a full profile page by slug or numeric ID from `/profiles/:identifier.json`; returns a typed `Profile::Practitioner` or `Profile::Organization` with `partial: false`
+- **`TocDoc::Profile#skills`** — returns all skills across every practice as an array of `TocDoc::Resource` objects
+- **`TocDoc::Profile#skills_for(practice_id)`** — returns skills for a single practice
+- **`TocDoc.profile`** — top-level shortcut delegating to `TocDoc::Profile.find`
+- **`TocDoc::Resource.main_attrs`** — class macro declaring which attribute keys appear in `#inspect`; inheritable by subclasses
+- **`TocDoc::Resource.normalize_attrs`** — extracted as a public class method (string-key normalisation)
+- **`TocDoc::Resource#inspect`** — custom implementation using `main_attrs` when declared, falling back to all keys
+
+### Changed
+
+- **`TocDoc::Profile.build`** — updated to resolve full profile responses via boolean flags (`is_practitioner` / `organization`) in addition to the existing `owner_type` path used for search results; profiles built from search results are now tagged `partial: true`, full fetches `partial: false`; a `force_full_profile` flag on a search result transparently delegates to `Profile.find`
+- **`TocDoc::Profile`** — `main_attrs :id, :partial` declared so inspect output stays concise
+
 ## [1.3.0] - 2026-03-15
 
 ### Added

data/README.md

@@ -28,6 +28,8 @@ A Ruby gem for interacting with the (unofficial) Doctolib API. A thin, Faraday-b
 4. [Endpoints](#endpoints)
    - [Availabilities](#availabilities)
    - [Search](#search)
+   - [Profile](#profile)
+   - [BookingInfo](#bookinginfo)
 5. [Response objects](#response-objects)
 6. [Pagination](#pagination)
 7. [Error handling](#error-handling)
@@ -128,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.3.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. |
@@ -209,6 +211,66 @@ Valid `type:` values: `'profile'` (all profiles), `'practitioner'`, `'organizati
 
 **Return value:** a `TocDoc::Search::Result` when `type:` is omitted, or a filtered `Array` otherwise (see [Response objects](#response-objects)).
 
+### Profile
+
+Fetch a full practitioner or organization profile page by slug or numeric ID.
+
+```ruby
+# by slug
+profile = TocDoc::Profile.find('jane-doe-bordeaux')
+
+# by numeric ID
+profile = TocDoc::Profile.find(1_542_899)
+
+# module-level shortcut
+profile = TocDoc.profile('jane-doe-bordeaux')
+```
+
+`Profile.find` returns a typed `TocDoc::Profile::Practitioner` or `TocDoc::Profile::Organization` instance with `partial: false` (i.e. full profile data).
+
+```ruby
+profile.name            # => "Dr. Jane Doe"
+profile.partial         # => false
+profile.practitioner?   # => true
+
+profile.skills          # => [#<TocDoc::Resource ...>, ...]
+profile.skills_for(377_272)  # => skills for a specific practice
+
+profile.places.first.city              # => "Bordeaux"
+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
@@ -270,15 +332,73 @@ Returned by `TocDoc::Search.where` when `type:` is omitted.
 
 ### `TocDoc::Profile`
 
-Represents a search profile result (practitioner or organization). Use `Profile.build(attrs)` to obtain the correctly typed subclass instance.
+Represents a practitioner or organization profile. Can be a lightweight search result (`partial: true`) or a full profile page (`partial: false`).
 
 | Method | Type | Description |
 |---|---|---|
-| `Profile.build(attrs)` | `Profile::Practitioner \| Profile::Organization` | Factory: returns `Practitioner` when `owner_type` is `"Account"`, `Organization` otherwise. |
+| `Profile.find(identifier)` | `Profile::Practitioner \| Profile::Organization` | Fetches a full profile by slug or numeric ID. Returns `partial: false`. |
+| `Profile.build(attrs)` | `Profile::Practitioner \| Profile::Organization` | Factory used internally by `Search::Result`; resolves type from `owner_type` or boolean flags. Returns `partial: true` for search results. |
+| `#id` | `String \| Integer` | Profile identifier. |
+| `#partial` | `Boolean` | `true` when built from a search result, `false` when fetched via `Profile.find`. |
 | `#practitioner?` | `Boolean` | `true` when this is a `Profile::Practitioner`. |
 | `#organization?` | `Boolean` | `true` when this is a `Profile::Organization`. |
+| `#places` | `Array<TocDoc::Place>` | Practice locations (available on full profiles). |
+| `#skills` | `Array<TocDoc::Resource>` | All skills across every practice (available on full profiles). |
+| `#skills_for(practice_id)` | `Array<TocDoc::Resource>` | Skills for a single practice by its ID. |
+
+`TocDoc::Profile::Practitioner` and `TocDoc::Profile::Organization` are typed subclasses that inherit dot-notation attribute access from `TocDoc::Resource`.
+
+### `TocDoc::Place`
+
+Represents a practice location returned inside a full profile response. Inherits dot-notation attribute access from `TocDoc::Resource`.
+
+| Method | Type | Description |
+|---|---|---|
+| `#id` | `String` | Practice identifier (e.g. `"practice-125055"`). |
+| `#address` | `String` | Street address. |
+| `#zipcode` | `String` | Postal code. |
+| `#city` | `String` | City name. |
+| `#full_address` | `String` | Combined address string. |
+| `#landline_number` | `String \| nil` | Phone number, if available. |
+| `#latitude` | `Float` | Latitude. |
+| `#longitude` | `Float` | Longitude. |
+| `#elevator` | `Boolean` | Whether the practice has elevator access. |
+| `#handicap` | `Boolean` | Whether the practice is handicap-accessible. |
+| `#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`
 
-`TocDoc::Profile::Practitioner` and `TocDoc::Profile::Organization` are thin subclasses that inherit dot-notation attribute access from `TocDoc::Resource`.
+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`
 

data/TODO.md

@@ -2,17 +2,6 @@
 
 [POTENTIAL_ENDPOINTS][POTENTIAL_ENDPOINTS.md]
 
-## 1.4
-
-- [ ] Profile
-  - slug : https://www.doctolib.fr/profiles/mathilde-devun-lesparre-medoc.json
-  - id : https://www.doctolib.fr/profiles/926388.json
-
-## 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
@@ -33,6 +22,18 @@
 
 # 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
+  - from slug : https://www.doctolib.fr/profiles/jane-doe-bordeaux.json
+  - from id : https://www.doctolib.fr/profiles/926388.json
+
 ## 1.3
 
 - [x] Search (autocomplete)

data/lib/toc_doc/core/version.rb

@@ -4,5 +4,5 @@ module TocDoc
   # The current version of the TocDoc gem.
   #
   # @return [String]
-  VERSION = '1.3.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/place.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TocDoc
+  # Represents a practice location returned inside a profile response.
+  #
+  # All fields are accessible via dot-notation inherited from {TocDoc::Resource}.
+  # Nested arrays (+opening_hours+, +stations+) are returned as raw arrays of hashes.
+  #
+  # @example
+  #   place = TocDoc::Place.new(
+  #     'id'               => 'practice-125055',
+  #     'address'          => '1 Rue Anonyme',
+  #     'zipcode'          => '33000',
+  #     'city'             => 'Bordeaux',
+  #     'full_address'     => '1 Rue Anonyme, 33000 Bordeaux',
+  #     'landline_number'  => '05 23 45 67 89',
+  #     'latitude'         => 44.8386722,
+  #     'longitude'        => -0.5780466,
+  #     'elevator'         => true,
+  #     'handicap'         => true,
+  #     'formal_name'      => 'Centre de santé - Anonyme'
+  #   )
+  #   place.id               #=> "practice-125055"
+  #   place.city             #=> "Bordeaux"
+  #   place.full_address     #=> "1 Rue Anonyme, 33000 Bordeaux"
+  #   place.landline_number  #=> "05 23 45 67 89"
+  #   place.latitude         #=> 44.8386722
+  #   place.elevator         #=> true
+  class Place < Resource
+    def coordinates
+      [latitude, longitude]
+    end
+  end
+end

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

@@ -3,6 +3,12 @@
 module TocDoc
   class Profile
     # A practitioner profile (raw +owner_type: "Account"+).
-    class Practitioner < Profile; end
+    class Practitioner < Profile
+      main_attrs :name_with_title
+
+      def to_s
+        (respond_to?(:name_with_title) && name_with_title) || name
+      end
+    end
   end
 end

data/lib/toc_doc/models/profile.rb

@@ -12,26 +12,154 @@ module TocDoc
   #   profile.practitioner?  #=> true
   #   profile.name           #=> "Dr Smith"
   class Profile < Resource
-    # Factory — returns a +Profile::Practitioner+ or +Profile::Organization+
-    # depending on the +owner_type+ field of the raw attribute hash.
-    #
-    # @param attrs [Hash] raw attribute hash from the API response
-    # @return [Profile::Practitioner, Profile::Organization]
-    def self.build(attrs = {})
-      case attrs['owner_type'] || attrs[:owner_type]
-      when 'Account'
-        Practitioner.new(attrs)
-      else
-        Organization.new(attrs)
+    PATH = '/profiles/%<identifier>s.json'
+
+    main_attrs :id, :partial
+
+    class << self
+      # Factory — returns a +Profile::Practitioner+ or +Profile::Organization+.
+      #
+      # 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']
+
+        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.
+      #
+      # @param identifier [String, Integer] profile slug or numeric ID
+      # @return [Profile::Practitioner, Profile::Organization]
+      # @raise [ArgumentError] if +identifier+ is +nil+
+      #
+      # @example
+      #   TocDoc::Profile.find('jane-doe-bordeaux')
+      #   TocDoc::Profile.find(1542899)
+      def find(identifier)
+        raise ArgumentError, 'identifier cannot be nil' if identifier.nil?
+
+        data = TocDoc.client.get(format(PATH, identifier: identifier))['data']
+        build(profile_attrs(data))
+      end
+
+      private
+
+      # 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']
+          Organization.new(attrs.merge('partial' => false))
+        else
+          raise ArgumentError, "Unable to determine profile type from attributes: #{attrs.inspect}"
+        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'] || {}),
+          'places' => Array(data['places']).map { |p| TocDoc::Place.new(p) },
+          'legals' => data['legals'],
+          'details' => data['details'],
+          'fees' => data['fees'],
+          'bookable' => data['bookable']
+        )
       end
     end
 
+    # 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) }
+    end
+
+    # Returns skills for a single practice as an array of {TocDoc::Resource}.
+    #
+    # @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/resource.rb

@@ -14,9 +14,43 @@ module TocDoc
   #   resource[:date] #=> "2026-02-28"
   #   resource.to_h   #=> { "date" => "2026-02-28", "slots" => [] }
   class Resource
+    class << self
+      # Normalises a raw attribute hash to string keys, mirroring what
+      # {#initialize} does internally. Useful in class-level factory methods
+      # that need to inspect attrs before wrapping them in a Resource instance.
+      #
+      # @param attrs [Hash] raw hash with string or symbol keys
+      # @return [Hash{String => Object}]
+      def normalize_attrs(attrs)
+        attrs.transform_keys(&:to_s)
+      end
+
+      # Declares which attribute keys are shown in +#inspect+.
+      # When called with arguments, sets the list for this class.
+      # When called with no arguments, returns the list (or +nil+ if unset),
+      # walking the ancestor chain so subclasses inherit the declaration.
+      #
+      # Subclasses that never call +main_attrs+ fall back to showing all attrs.
+      #
+      # @example
+      #   main_attrs :id, :name, :slug
+      #
+      # @param keys [Array<Symbol, String>]
+      # @return [Array<String>, nil]
+      def main_attrs(*keys)
+        if keys.empty?
+          ancestor = ancestors.find { |a| a.instance_variable_defined?(:@main_attrs) }
+          ancestor&.instance_variable_get(:@main_attrs)
+        else
+          inherited = superclass.respond_to?(:main_attrs) ? (superclass.main_attrs || []) : []
+          @main_attrs = (inherited + keys.map(&:to_s)).uniq
+        end
+      end
+    end
+
     # @param attrs [Hash] the raw attribute hash (string or symbol keys)
     def initialize(attrs = {})
-      @attrs = attrs.transform_keys(&:to_s)
+      @attrs = self.class.normalize_attrs(attrs)
     end
 
     # Read an attribute by name.
@@ -56,7 +90,7 @@ module TocDoc
     def ==(other)
       case other
       when Resource then @attrs == other.to_h
-      when Hash     then @attrs == other.transform_keys(&:to_s)
+      when Hash     then @attrs == self.class.normalize_attrs(other)
       else false
       end
     end
@@ -78,5 +112,12 @@ module TocDoc
       key = method_name.to_s
       @attrs.key?(key) ? @attrs[key] : super
     end
+
+    # @!visibility private
+    def inspect
+      keys  = self.class.main_attrs || @attrs.keys
+      pairs = keys.map { |k| "@#{k}=#{@attrs[k.to_s].inspect}" }.join(', ')
+      "#<#{self.class} #{pairs}>"
+    end
   end
 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

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 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'
 require 'toc_doc/models/availability/collection'
 
 require 'toc_doc/models/profile'
-require 'toc_doc/models/speciality'

data/lib/toc_doc.rb

@@ -89,6 +89,28 @@ module TocDoc
       TocDoc::Search.where(**)
     end
 
+    # Fetches a full profile page by slug or numeric ID.
+    #
+    # Delegates to {TocDoc::Profile.find} — see that method for full
+    # parameter documentation.
+    #
+    # @param identifier [String, Integer] profile slug or numeric ID
+    # @return [TocDoc::Profile::Practitioner, TocDoc::Profile::Organization]
+    def profile(identifier)
+      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.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - 01max
@@ -74,8 +74,11 @@ 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
 - lib/toc_doc/models/profile/practitioner.rb
@@ -83,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: