toc_doc 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a6c39bc2d41f1be6ae2b12b23074de967614fc1c6067d217316c7cb8bb9f0c31
-  data.tar.gz: 6c3a8732a25916bb75ebb18c7f53a79ff272a0c8b646477160a8381890404dcf
+  metadata.gz: 97e03e2d5bbc3fffa25a74e1dc6367d27befc2c25009889ff55b25c2f0abad46
+  data.tar.gz: 847c1832c1a927024404004c11c3adb966142d6e93df3de2692d9734f400b2d2
 SHA512:
-  metadata.gz: dde234124b736d0149ac1f45bb6ab654487fb4e0c91bffb6c1b2462f51fa50a94cb59c5e9d4c4c5ef688eb12b9a8f8f321a0b5384b7d4bebe375506f81001b87
-  data.tar.gz: 1fd5632c3e5c73f89ae8db6f844269d5674141332ea9fd1956691695c3ae7242a7d7f706b3b0742f361df6b7a6a8ed931dc25f6d4b2c01426c6cc0ee379dacde
+  metadata.gz: fe6ff537f03f02a3ecc17013558bcbe165667cc2bb1275d9cea12f28e84457672b278bdfc7f6e00a7f894be7ce5f3587bf02f70d2f6e5f7f70c0c2109372a145
+  data.tar.gz: c710d06fb3b1137c1ff2bc4a5f8c9a79c527c7c8e777d99bffd4f11f6799ae4c8dad188a558ac6f29a4696bde45eeb70ffb62b396a2e17cc6805005cf381cb41

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [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

data/README.md

@@ -28,6 +28,7 @@ A Ruby gem for interacting with the (unofficial) Doctolib API. A thin, Faraday-b
 4. [Endpoints](#endpoints)
    - [Availabilities](#availabilities)
    - [Search](#search)
+   - [Profile](#profile)
 5. [Response objects](#response-objects)
 6. [Pagination](#pagination)
 7. [Error handling](#error-handling)
@@ -128,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.3.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. |
@@ -209,6 +210,37 @@ 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)).
+
 ---
 
 ## Response objects
@@ -270,15 +302,40 @@ 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::Profile::Practitioner` and `TocDoc::Profile::Organization` are thin 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`
 

data/TODO.md

@@ -2,12 +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
@@ -33,6 +27,12 @@
 
 # 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)

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.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/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
+        name_with_title || name
+      end
+    end
   end
 end

data/lib/toc_doc/models/profile.rb

@@ -12,20 +12,86 @@ 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 (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)

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.rb

@@ -1,10 +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'
-require 'toc_doc/models/speciality'

data/lib/toc_doc.rb

@@ -89,6 +89,17 @@ 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
+
     # @!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.4.0
 platform: ruby
 authors:
 - 01max
@@ -76,6 +76,7 @@ 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