toc_doc 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcac91743cd8f8d50d032638c3a690f88c786a369960d8b5df8bdead6006149c
-  data.tar.gz: d8df90b16b2ff3e2311af4751396ff1ae54173575e4507989df0e7c910bd82eb
+  metadata.gz: a6c39bc2d41f1be6ae2b12b23074de967614fc1c6067d217316c7cb8bb9f0c31
+  data.tar.gz: 6c3a8732a25916bb75ebb18c7f53a79ff272a0c8b646477160a8381890404dcf
 SHA512:
-  metadata.gz: e8886203725b1dd9bbd59e62ee56aaf4f0965c908b31d478568c9d0149a7062f7059509f5692f18273e08b4a05d90d8a6d6e8bb02e89342ab2d1a18e92b2b16a
-  data.tar.gz: fd9271676246e8da0e7e626ebc3c10316f5b86b2ab6fc811a67986bb276aa1e817c74f7d17fec64372cfb15048638b1aac32e08b2dce981142646ed4a1289977
+  metadata.gz: dde234124b736d0149ac1f45bb6ab654487fb4e0c91bffb6c1b2462f51fa50a94cb59c5e9d4c4c5ef688eb12b9a8f8f321a0b5384b7d4bebe375506f81001b87
+  data.tar.gz: 1fd5632c3e5c73f89ae8db6f844269d5674141332ea9fd1956691695c3ae7242a7d7f706b3b0742f361df6b7a6a8ed931dc25f6d4b2c01426c6cc0ee379dacde

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [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,7 @@ 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)
 5. [Response objects](#response-objects)
 6. [Pagination](#pagination)
 7. [Error handling](#error-handling)
@@ -127,7 +128,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.3.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 +181,34 @@ 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)).
+
 ---
 
 ## Response objects
@@ -229,6 +258,51 @@ 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 search profile result (practitioner or organization). Use `Profile.build(attrs)` to obtain the correctly typed subclass instance.
+
+| Method | Type | Description |
+|---|---|---|
+| `Profile.build(attrs)` | `Profile::Practitioner \| Profile::Organization` | Factory: returns `Practitioner` when `owner_type` is `"Account"`, `Organization` otherwise. |
+| `#practitioner?` | `Boolean` | `true` when this is a `Profile::Practitioner`. |
+| `#organization?` | `Boolean` | `true` when this is a `Profile::Organization`. |
+
+`TocDoc::Profile::Practitioner` and `TocDoc::Profile::Organization` are thin subclasses that inherit dot-notation attribute access from `TocDoc::Resource`.
+
+### `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,12 +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
@@ -33,8 +27,27 @@
 - [ ] Authentication module + headers
 - [ ] Auth specs
 
+# ???
+
+- [ ] Figure what is `organization_statuses` in the autocomplete endpoint and what to do with it.
+
 # DONE & RELEASED
 
+## 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.3.0'
 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,8 @@
+# frozen_string_literal: true
+
+module TocDoc
+  class Profile
+    # A practitioner profile (raw +owner_type: "Account"+).
+    class Practitioner < Profile; end
+  end
+end

data/lib/toc_doc/models/profile.rb

@@ -0,0 +1,42 @@
+# 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
+    # 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)
+      end
+    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/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,10 @@
 # frozen_string_literal: true
 
 require 'toc_doc/models/resource'
+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

@@ -76,6 +76,19 @@ 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
+
     # @!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.3.0
 platform: ruby
 authors:
 - 01max
@@ -76,7 +76,13 @@ files:
 - lib/toc_doc/models.rb
 - lib/toc_doc/models/availability.rb
 - lib/toc_doc/models/availability/collection.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: