toc_doc 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcac91743cd8f8d50d032638c3a690f88c786a369960d8b5df8bdead6006149c
-  data.tar.gz: d8df90b16b2ff3e2311af4751396ff1ae54173575e4507989df0e7c910bd82eb
+  metadata.gz: 97e03e2d5bbc3fffa25a74e1dc6367d27befc2c25009889ff55b25c2f0abad46
+  data.tar.gz: 847c1832c1a927024404004c11c3adb966142d6e93df3de2692d9734f400b2d2
 SHA512:
-  metadata.gz: e8886203725b1dd9bbd59e62ee56aaf4f0965c908b31d478568c9d0149a7062f7059509f5692f18273e08b4a05d90d8a6d6e8bb02e89342ab2d1a18e92b2b16a
-  data.tar.gz: fd9271676246e8da0e7e626ebc3c10316f5b86b2ab6fc811a67986bb276aa1e817c74f7d17fec64372cfb15048638b1aac32e08b2dce981142646ed4a1289977
+  metadata.gz: fe6ff537f03f02a3ecc17013558bcbe165667cc2bb1275d9cea12f28e84457672b278bdfc7f6e00a7f894be7ce5f3587bf02f70d2f6e5f7f70c0c2109372a145
+  data.tar.gz: c710d06fb3b1137c1ff2bc4a5f8c9a79c527c7c8e777d99bffd4f11f6799ae4c8dad188a558ac6f29a4696bde45eeb70ffb62b396a2e17cc6805005cf381cb41

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## [Unreleased]
 
+## [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
+
+- **`TocDoc::Speciality`** — new `Resource`-based model representing a speciality returned by the autocomplete endpoint; exposes `#value`, `#slug`, and `#name` via dot-notation
+- **`TocDoc::Profile`** — new `Resource`-based model for search profile results; `Profile.build(attrs)` factory returns a `Profile::Practitioner` or `Profile::Organization` based on the `owner_type` field; provides `#practitioner?` and `#organization?` predicates
+- **`TocDoc::Profile::Practitioner`** and **`TocDoc::Profile::Organization`** — typed profile subclasses
+- **`TocDoc::Search`** — new service class for the autocomplete endpoint (`/api/searchbar/autocomplete.json`); `Search.where(query:, type: nil, **options)` fetches results and returns a `Search::Result`, or a filtered array when `type:` is one of `'profile'`, `'practitioner'`, `'organization'`, or `'speciality'`
+- **`TocDoc::Search::Result`** — envelope returned by `Search.where`; exposes `#profiles` (typed via `Profile.build`) and `#specialities`; `#filter_by_type` narrows to a specific kind
+- **`TocDoc.search`** — top-level shortcut delegating to `TocDoc::Search.where`
+
 ## [1.2.0] - 2026-03-08
 
 ### Added

data/README.md

@@ -27,6 +27,8 @@ A Ruby gem for interacting with the (unofficial) Doctolib API. A thin, Faraday-b
    - [ENV variables](#environment-variable-overrides)
 4. [Endpoints](#endpoints)
    - [Availabilities](#availabilities)
+   - [Search](#search)
+   - [Profile](#profile)
 5. [Response objects](#response-objects)
 6. [Pagination](#pagination)
 7. [Error handling](#error-handling)
@@ -127,7 +129,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.2.0` | `User-Agent` header sent with every request. |
+| `user_agent` | `TocDoc Ruby Gem 1.4.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. |
@@ -180,6 +182,65 @@ TocDoc::Availability.where(
 
 **Return value:** a `TocDoc::Availability::Collection` (see [Response objects](#response-objects)).
 
+### Search
+
+Query the Doctolib autocomplete endpoint to look up practitioners, organizations, and specialities.
+
+```ruby
+result = TocDoc::Search.where(query: 'dentiste')
+result.profiles      # => [#<TocDoc::Profile::Practitioner ...>, ...]
+result.specialities  # => [#<TocDoc::Speciality ...>, ...]
+```
+
+Pass `type:` to receive a filtered array directly:
+
+```ruby
+# Only specialities
+TocDoc::Search.where(query: 'cardio', type: 'speciality')
+# => [#<TocDoc::Speciality name="Cardiologue">, ...]
+
+# Only practitioners
+TocDoc::Search.where(query: 'dupont', type: 'practitioner')
+# => [#<TocDoc::Profile::Practitioner ...>, ...]
+```
+
+Valid `type:` values: `'profile'` (all profiles), `'practitioner'`, `'organization'`, `'speciality'`.
+
+`TocDoc.search(...)` is a module-level shortcut with the same signature.
+
+**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)).
+
 ---
 
 ## Response objects
@@ -229,6 +290,76 @@ collection.to_h
 #    }
 ```
 
+### `TocDoc::Search::Result`
+
+Returned by `TocDoc::Search.where` when `type:` is omitted.
+
+| Method | Type | Description |
+|---|---|---|
+| `#profiles` | `Array<TocDoc::Profile::Practitioner, TocDoc::Profile::Organization>` | All profile results, typed via `Profile.build`. |
+| `#specialities` | `Array<TocDoc::Speciality>` | All speciality results. |
+| `#filter_by_type(type)` | `Array` | Narrows results to `'profile'`, `'practitioner'`, `'organization'`, or `'speciality'`. |
+
+### `TocDoc::Profile`
+
+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.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::Speciality`
+
+Represents a speciality returned by the autocomplete endpoint. Inherits dot-notation attribute access from `TocDoc::Resource`.
+
+| Method | Type | Description |
+|---|---|---|
+| `#value` | `Integer` | Numeric speciality identifier. |
+| `#slug` | `String` | URL-friendly identifier. |
+| `#name` | `String` | Human-readable speciality name. |
+
+**Example:**
+
+```ruby
+result = TocDoc::Search.where(query: 'dermato')
+
+result.profiles.first.class          # => TocDoc::Profile::Practitioner
+result.profiles.first.practitioner?  # => true
+result.profiles.first.name           # => "Dr. Jane Smith"
+
+result.specialities.first.slug   # => "dermatologue"
+result.specialities.first.name   # => "Dermatologue"
+```
+
 ---
 
 ## Pagination

data/TODO.md

@@ -2,18 +2,6 @@
 
 [POTENTIAL_ENDPOINTS][POTENTIAL_ENDPOINTS.md]
 
-## 1.3
-
-- [ ] Search (autocomplete)
-  - [ ] search profile : https://www.doctolib.fr/api/searchbar/autocomplete.json?search=devun
-  - [ ] search specialty : https://www.doctolib.fr/api/searchbar/autocomplete.json?search=dentiste
-
-## 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
@@ -33,8 +21,33 @@
 - [ ] Authentication module + headers
 - [ ] Auth specs
 
+# ???
+
+- [ ] Figure what is `organization_statuses` in the autocomplete endpoint and what to do with it.
+
 # DONE & RELEASED
 
+## 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)
+  - [x] search profile : https://www.doctolib.fr/api/searchbar/autocomplete.json?search=devun
+  - [x] search specialty : https://www.doctolib.fr/api/searchbar/autocomplete.json?search=dentiste
+
+## 1.2
+
+- [x] Rework Availability's client, model and collection architecture.
+
+## 1.1
+
+### Parse raw API data
+- [x] Parse date / datetime
+
 ## 1.0
 
 ### 1 – Skeleton & Tooling
@@ -88,13 +101,4 @@
   - [x] on rubygem
   - [x] release on GH
   - [x] gem.coop/@maxime
-- [x] Add test coverage tool
-
-## 1.1
-
-### Parse raw API data
-- [x] Parse date / datetime
-
-## 1.2
-
-- [x] Rework Availability's client, model and collection architecture.
+- [x] Add test coverage tool

data/lib/toc_doc/core/version.rb

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module TocDoc
+  class Profile
+    # An organization profile.
+    class Organization < Profile; end
+  end
+end

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module TocDoc
+  class Profile
+    # A practitioner profile (raw +owner_type: "Account"+).
+    class Practitioner < Profile
+      main_attrs :name_with_title
+
+      def to_s
+        name_with_title || name
+      end
+    end
+  end
+end

data/lib/toc_doc/models/profile.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module TocDoc
+  # Represents a search profile result (practitioner or organization).
+  # Inherits dot-notation attribute access from +TocDoc::Resource+.
+  #
+  # Use +Profile.build+ to obtain the correctly typed subclass instance.
+  #
+  # @example
+  #   profile = TocDoc::Profile.build('owner_type' => 'Account', 'name' => 'Dr Smith')
+  #   profile.class          #=> TocDoc::Profile::Practitioner
+  #   profile.practitioner?  #=> true
+  #   profile.name           #=> "Dr Smith"
+  class Profile < Resource
+    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 (search 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]
+      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
+      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
+
+      def build_from_flags(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
+
+      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>]
+    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>]
+    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
+    def practitioner?
+      is_a?(Practitioner)
+    end
+
+    # @return [Boolean] true when this profile is an organization
+    def organization?
+      is_a?(Organization)
+    end
+  end
+end
+
+require 'toc_doc/models/profile/practitioner'
+require 'toc_doc/models/profile/organization'

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/search/result.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'toc_doc/models/profile'
+require 'toc_doc/models/speciality'
+
+module TocDoc
+  class Search
+    # Envelope returned by {TocDoc::Search.where} when no +type:+ filter is given.
+    #
+    # Wraps the raw API response and exposes typed collections for profiles and
+    # specialities.  Unlike {TocDoc::Availability::Collection} this class does
+    # NOT include +Enumerable+ — the dual-type nature of the result does not
+    # lend itself to a single iteration interface.
+    #
+    # @example
+    #   result = TocDoc::Search.where(query: 'dentiste')
+    #   result.profiles      #=> [#<TocDoc::Profile::Practitioner>, ...]
+    #   result.specialities  #=> [#<TocDoc::Speciality>, ...]
+    class Result
+      # @param data [Hash] raw parsed response body from the autocomplete endpoint
+      def initialize(data)
+        @profiles     = build_profiles(data['profiles'])
+        @specialities = build_specialities(data['specialities'])
+      end
+
+      # All profile results, typed as {TocDoc::Profile::Practitioner} or
+      # {TocDoc::Profile::Organization} via {TocDoc::Profile.build}.
+      #
+      # @return [Array<TocDoc::Profile::Practitioner, TocDoc::Profile::Organization>]
+      attr_reader :profiles
+
+      # All speciality results as {TocDoc::Speciality} instances.
+      #
+      # @return [Array<TocDoc::Speciality>]
+      attr_reader :specialities
+
+      # Returns a subset of results narrowed to the given type.
+      #
+      # @param type [String] one of +'profile'+, +'practitioner'+, +'organization'+, +'speciality'+
+      # @return [Array<TocDoc::Profile>, Array<TocDoc::Speciality>]
+      def filter_by_type(type)
+        case type
+        when 'profile'      then profiles
+        when 'practitioner' then profiles.select(&:practitioner?)
+        when 'organization' then profiles.select(&:organization?)
+        when 'speciality'   then specialities
+        end
+      end
+
+      private
+
+      def build_profiles(raw)
+        Array(raw).map { |attrs| TocDoc::Profile.build(attrs) }
+      end
+
+      def build_specialities(raw)
+        Array(raw).map { |attrs| TocDoc::Speciality.new(attrs) }
+      end
+    end
+  end
+end

data/lib/toc_doc/models/search.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'toc_doc/models/search/result'
+
+module TocDoc
+  # Entry point for the autocomplete / search endpoint.
+  #
+  # Unlike {TocDoc::Availability}, +Search+ is not itself a resource — it is a
+  # plain service class that wraps the API call and returns a typed result.
+  #
+  # @example Fetch everything
+  #   result = TocDoc::Search.where(query: 'dentiste')
+  #   result          #=> #<TocDoc::Search::Result>
+  #   result.profiles #=> [#<TocDoc::Profile::Practitioner>, ...]
+  #
+  # @example Filter by type
+  #   TocDoc::Search.where(query: 'dentiste', type: 'practitioner')
+  #   #=> [#<TocDoc::Profile::Practitioner>, ...]
+  class Search
+    PATH = '/api/searchbar/autocomplete.json'
+    VALID_TYPES = %w[profile practitioner organization speciality].freeze
+
+    class << self
+      # Queries the autocomplete endpoint and returns a {Search::Result} or a
+      # filtered array.
+      #
+      # The +type:+ keyword is handled client-side only — it is never forwarded
+      # to the API.  The full response is always fetched; narrowing happens after.
+      #
+      # @param query [String] the search term
+      # @param type [String, nil] optional filter; one of +'profile'+,
+      #   +'practitioner'+, +'organization'+, +'speciality'+
+      # @param options [Hash] additional query params forwarded verbatim to the API
+      # @return [Search::Result] when +type:+ is +nil+
+      # @return [Array<TocDoc::Profile>] when +type:+ is +'profile'+, +'practitioner'+,
+      #   or +'organization'+
+      # @return [Array<TocDoc::Speciality>] when +type:+ is +'speciality'+
+      # @raise [ArgumentError] if +type:+ is not +nil+ and not in {VALID_TYPES}
+      #
+      # @example
+      #   TocDoc::Search.where(query: 'derma', type: 'speciality')
+      #   #=> [#<TocDoc::Speciality name="Dermatologue">, ...]
+      def where(query:, type: nil, **options)
+        if !type.nil? && !VALID_TYPES.include?(type)
+          raise ArgumentError, "Invalid type #{type.inspect}. Must be one of: #{VALID_TYPES.join(', ')}"
+        end
+
+        data   = TocDoc.client.get(PATH, query: { search: query, **options })
+        result = Result.new(data)
+
+        type.nil? ? result : result.filter_by_type(type)
+      end
+    end
+  end
+end

data/lib/toc_doc/models/speciality.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TocDoc
+  # Represents a speciality returned by the autocomplete endpoint.
+  #
+  # All fields (+value+, +slug+, +name+) are primitives and are accessed via
+  # dot-notation inherited from {TocDoc::Resource}.
+  #
+  # @example
+  #   speciality = TocDoc::Speciality.new('value' => 228, 'slug' => 'homeopathe', 'name' => 'Homéopathe')
+  #   speciality.value  #=> 228
+  #   speciality.slug   #=> "homeopathe"
+  #   speciality.name   #=> "Homéopathe"
+  class Speciality < Resource
+  end
+end

data/lib/toc_doc/models.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
 require 'toc_doc/models/resource'
+require 'toc_doc/models/speciality'
+require 'toc_doc/models/place'
+require 'toc_doc/models/search'
+
 require 'toc_doc/models/availability'
 require 'toc_doc/models/availability/collection'
+
+require 'toc_doc/models/profile'

data/lib/toc_doc.rb

@@ -76,6 +76,30 @@ module TocDoc
       TocDoc::Availability.where(**)
     end
 
+    # Queries the autocomplete / search endpoint.
+    #
+    # Delegates to {TocDoc::Search.where} — see that method for full
+    # parameter documentation.
+    #
+    # @return [TocDoc::Search::Result] when called without +type:+
+    # @return [Array<TocDoc::Profile>] when +type:+ is +'profile'+,
+    #   +'practitioner'+, or +'organization'+
+    # @return [Array<TocDoc::Speciality>] when +type:+ is +'speciality'+
+    def search(**)
+      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
+
     # @!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.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - 01max
@@ -76,7 +76,14 @@ files:
 - lib/toc_doc/models.rb
 - lib/toc_doc/models/availability.rb
 - lib/toc_doc/models/availability/collection.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
 - lib/toc_doc/models/resource.rb
+- lib/toc_doc/models/search.rb
+- lib/toc_doc/models/search/result.rb
+- lib/toc_doc/models/speciality.rb
 - sig/toc_doc.rbs
 homepage: https://github.com/01max/toc_doc
 licenses: