toc_doc 1.1.0 → 1.3.0

data/lib/toc_doc/core/uri_utils.rb

@@ -5,13 +5,13 @@ module TocDoc
   #
   # Doctolib expects certain ID list parameters to be dash-joined strings
   # rather than standard repeated/bracket array notation. Include this module
-  # into endpoint modules and call +dashed_ids+ explicitly for each such param:
+  # and call +dashed_ids+ explicitly for each such param:
   #
-  #   module TocDoc::Client::Availabilities
-  #     include TocDoc::UriUtils
+  #   class TocDoc::Availability
+  #     extend TocDoc::UriUtils
   #
-  #     def availabilities(visit_motive_ids:, agenda_ids:, **opts)
-  #       get('/availabilities.json', query: {
+  #     def self.where(visit_motive_ids:, agenda_ids:, **opts)
+  #       client.get('/availabilities.json', query: {
   #         visit_motive_ids: dashed_ids(visit_motive_ids),
   #         agenda_ids:       dashed_ids(agenda_ids),
   #         **opts

data/lib/toc_doc/core/version.rb

@@ -4,5 +4,5 @@ module TocDoc
   # The current version of the TocDoc gem.
   #
   # @return [String]
-  VERSION = '1.1.0'
+  VERSION = '1.3.0'
 end

data/lib/toc_doc/models/availability/collection.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'toc_doc/models/availability'
+
+module TocDoc
+  class Availability
+    # An Enumerable collection of {TocDoc::Availability} instances returned
+    # by {TocDoc::Availability.where}.
+    #
+    # @example Iterate over available slots
+    #   collection = TocDoc::Availability.where(visit_motive_ids: 123, agenda_ids: 456)
+    #   collection.each { |avail| puts avail.date }
+    #
+    # @example Access metadata
+    #   collection.total      #=> 5
+    #   collection.next_slot  #=> "2026-02-28T10:00:00.000+01:00"
+    class Collection
+      include Enumerable
+
+      attr_reader :path, :query
+
+      # @param data [Hash] parsed first-page response body
+      # @param query [Hash] original query params (used to build next-page requests)
+      # @param path [String] API path for subsequent requests
+      def initialize(data, query: {}, path: '/availabilities.json')
+        @data = data.dup
+        @query = query
+        @path = path
+      end
+
+      # Iterates over {TocDoc::Availability} instances that have at least one slot.
+      #
+      # @yieldparam availability [TocDoc::Availability]
+      # @return [Enumerator] if no block given
+      def each(&)
+        filtered_entries.each(&)
+      end
+
+      # The total number of available slots in the collection.
+      #
+      # @return [Integer]
+      def total
+        @data['total']
+      end
+
+      # The nearest available appointment slot.
+      #
+      # Returns the +next_slot+ value from the API when present (which only
+      # occurs when none of the loaded dates have any slots).  Otherwise
+      # returns the first slot of the first date that has one.
+      #
+      # @return [String, nil] ISO 8601 datetime string, or +nil+ when unavailable
+      def next_slot
+        return @data['next_slot'] if @data.key?('next_slot')
+
+        Array(@data['availabilities']).each do |entry|
+          slots = Array(entry['slots'])
+          return slots.first unless slots.empty?
+        end
+
+        nil
+      end
+
+      # All date entries — including those with no slots — as {TocDoc::Availability}
+      # objects.
+      #
+      # @return [Array<TocDoc::Availability>]
+      def raw_availabilities
+        Array(@data['availabilities']).map { |entry| TocDoc::Availability.new(entry) }
+      end
+
+      # Returns a plain Hash representation of the collection.
+      #
+      # The +availabilities+ key contains only dates with slots (filtered),
+      # serialised back to plain Hashes.
+      #
+      # @return [Hash{String => Object}]
+      def to_h
+        @data.merge('availabilities' => filtered_entries.map(&:to_h))
+      end
+
+      # Fetches the next window of availabilities (starting the day after the
+      # last date in the current collection) and merges them in.
+      #
+      # @param page_data [Hash] parsed response body to merge into this collection
+      # @return [self]
+      def merge_page!(page_data)
+        @data['availabilities'] = @data.fetch('availabilities', []) + page_data.fetch('availabilities', [])
+        @data['total']          = @data.fetch('total', 0) + page_data.fetch('total', 0)
+        self
+      end
+
+      private
+
+      def filtered_entries
+        Array(@data['availabilities'])
+          .select { |entry| Array(entry['slots']).any? }
+          .map { |entry| TocDoc::Availability.new(entry) }
+      end
+    end
+  end
+end

data/lib/toc_doc/models/availability.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'date'
+require 'toc_doc/core/uri_utils'
 
 module TocDoc
   # Represents a single availability date entry returned by the Doctolib API.
@@ -12,9 +13,77 @@ module TocDoc
   #   avail.slots      #=> [#<DateTime: 2026-02-28T10:00:00.000+01:00>]
   #   avail.raw_slots  #=> ["2026-02-28T10:00:00.000+01:00"]
   class Availability < Resource
+    extend TocDoc::UriUtils
+
     attr_reader :date, :slots
 
-    # @param attrs [Hash] raw attributes from the API response, expected to include
+    PATH = '/availabilities.json'
+
+    class << self
+      # Fetches availabilities from the API and returns an {Availability::Collection}.
+      #
+      # When the API response contains a +next_slot+ key — indicating that no
+      # date in the current window has available slots — a second request is
+      # made automatically from that date before the collection is returned.
+      #
+      # @param visit_motive_ids [Integer, String, Array<Integer>]
+      #   one or more visit-motive IDs (dash-joined for the API)
+      # @param agenda_ids [Integer, String, Array<Integer>]
+      #   one or more agenda IDs (dash-joined for the API)
+      # @param start_date [Date, String]
+      #   earliest date to search from (default: +Date.today+)
+      # @param limit [Integer]
+      #   maximum availability dates per page (default: +TocDoc.per_page+)
+      # @param options [Hash]
+      #   additional query params forwarded verbatim to the API
+      # @return [TocDoc::Availability::Collection]
+      #
+      # @example
+      #   TocDoc::Availability.where(
+      #     visit_motive_ids: 7_767_829,
+      #     agenda_ids: [1_101_600],
+      #     start_date: Date.today
+      #   ).each { |avail| puts avail.date }
+      def where(visit_motive_ids:, agenda_ids:, start_date: Date.today,
+                limit: TocDoc.per_page, **options)
+        client = TocDoc.client
+        query  = build_query(visit_motive_ids, agenda_ids, start_date, limit, options)
+        data   = client.get(PATH, query: query)
+
+        merge_next_page(client, query, data) if data['next_slot']
+
+        Collection.new(data, query: query, path: PATH)
+      end
+
+      private
+
+      def merge_next_page(client, query, current_page)
+        next_date = Date.parse(current_page['next_slot']).to_s
+        next_page = client.get(PATH, query: query.merge(start_date: next_date))
+        merge_page_data(current_page, next_page)
+      end
+
+      def merge_page_data(current_page, next_page)
+        current_page['availabilities'] =
+          current_page.fetch('availabilities', []) + next_page.fetch('availabilities', [])
+        current_page['total']          = current_page.fetch('total', 0) + next_page.fetch('total', 0)
+        current_page.delete('next_slot')
+        current_page['next_slot'] = next_page['next_slot'] if next_page.key?('next_slot')
+      end
+
+      def build_query(visit_motive_ids, agenda_ids, start_date, limit, extra)
+        {
+          visit_motive_ids: dashed_ids(visit_motive_ids),
+          agenda_ids: dashed_ids(agenda_ids),
+          start_date: start_date.to_s,
+          limit: [limit.to_i, TocDoc::Default::MAX_PER_PAGE].min,
+          **extra
+        }
+      end
+    end
+
+    # @param attrs [Hash] raw attributes from the API response; expected to include
+    #   a +date+ key (ISO 8601 date string) and a +slots+ key (Array of ISO 8601 datetime strings)
     def initialize(*attrs)
       super
       raw = build_raw(@attrs)

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,6 +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/response/availability'
+require 'toc_doc/models/profile'
+require 'toc_doc/models/speciality'

data/lib/toc_doc.rb

@@ -16,13 +16,9 @@ require 'toc_doc/client'
 # Configuration can be set at the module level and will be inherited by every
 # {TocDoc::Client} instance created via {.client} or {.setup}.
 #
-# Any method available on {TocDoc::Client} can be called directly on `TocDoc`
-# and will be forwarded to the memoized {.client}.
-#
 # @example Quick start
 #   TocDoc.setup do |config|
 #     config.api_endpoint = 'https://www.doctolib.de'
-#     config.auto_paginate = true
 #   end
 #
 #   TocDoc.availabilities(
@@ -70,6 +66,29 @@ module TocDoc
       client
     end
 
+    # Returns available appointment slots.
+    #
+    # Delegates to {TocDoc::Availability.where} — see that method for full
+    # parameter documentation.
+    #
+    # @return [TocDoc::Availability::Collection]
+    def availabilities(**)
+      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.1.0
+  version: 1.3.0
 platform: ruby
 authors:
 - 01max
@@ -57,12 +57,12 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.md
+- POTENTIAL_ENDPOINTS.md
 - README.md
 - Rakefile
 - TODO.md
 - lib/toc_doc.rb
 - lib/toc_doc/client.rb
-- lib/toc_doc/client/availabilities.rb
 - lib/toc_doc/core/authentication.rb
 - lib/toc_doc/core/configurable.rb
 - lib/toc_doc/core/connection.rb
@@ -75,8 +75,14 @@ files:
 - lib/toc_doc/middleware/.keep
 - 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/response/availability.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:

data/lib/toc_doc/client/availabilities.rb

@@ -1,118 +0,0 @@
-# frozen_string_literal: true
-
-require 'date'
-
-module TocDoc
-  class Client
-    # Endpoint module for the Doctolib availabilities API.
-    #
-    # Included into {TocDoc::Client}; methods delegate to
-    # {TocDoc::Connection#get} via the enclosing client instance.
-    #
-    # @see https://www.doctolib.fr/availabilities.json Doctolib availability endpoint
-    module Availabilities
-      # Returns available appointment slots for the given visit motives and
-      # agendas.
-      #
-      # When +auto_paginate+ is enabled, all pages of results are
-      # fetched and merged automatically.
-      #
-      # @param visit_motive_ids [Integer, String, Array<Integer>]
-      #   one or more visit-motive IDs (dash-joined for the API)
-      # @param agenda_ids [Integer, String, Array<Integer>]
-      #   one or more agenda IDs (dash-joined for the API)
-      # @param start_date [Date, String]
-      #   earliest date to search from (default: +Date.today+)
-      # @param limit [Integer]
-      #   maximum number of availability dates per page
-      #   (default: +per_page+ config)
-      # @param options [Hash]
-      #   additional query params forwarded verbatim to the API
-      #   (e.g. +practice_ids:+, +telehealth:+)
-      # @return [TocDoc::Response::Availability] structured response object
-      #
-      # @example Fetch availabilities for a single practitioner
-      #   client.availabilities(
-      #     visit_motive_ids: 7_767_829,
-      #     agenda_ids: [1_101_600],
-      #     practice_ids: 377_272,
-      #     telehealth: false
-      #   )
-      #
-      # @example Via the module-level shortcut
-      #   TocDoc.availabilities(visit_motive_ids: 123, agenda_ids: 456)
-      def availabilities(visit_motive_ids:, agenda_ids:, start_date: Date.today, limit: per_page, **options)
-        base_query = build_availability_query(visit_motive_ids, agenda_ids, start_date, limit, options)
-
-        response = paginate('/availabilities.json', query: base_query) do |acc, last_resp|
-          paginate_availability_page(acc, last_resp, base_query)
-        end
-
-        TocDoc::Response::Availability.new(response)
-      end
-
-      private
-
-      # Builds the query hash sent to the availabilities endpoint.
-      #
-      # @param visit_motive_ids [Integer, String, Array] raw motive IDs
-      # @param agenda_ids [Integer, String, Array] raw agenda IDs
-      # @param start_date [Date, String] earliest search date
-      # @param limit [Integer] page size
-      # @param extra [Hash] additional query params
-      # @return [Hash{Symbol => Object}] ready-to-send query hash
-      def build_availability_query(visit_motive_ids, agenda_ids, start_date, limit, extra)
-        {
-          visit_motive_ids: dashed_ids(visit_motive_ids),
-          agenda_ids: dashed_ids(agenda_ids),
-          start_date: start_date.to_s,
-          limit: [limit.to_i, TocDoc::Default::MAX_PER_PAGE].min,
-          **extra
-        }
-      end
-
-      # Merges the latest page body into the accumulator and returns options
-      # for the next page, or +nil+ to halt pagination.
-      #
-      # On the first yield +acc+ *is* the first-page body (identical object),
-      # so the merge step is skipped.
-      #
-      # @param acc [Hash] growing accumulator
-      # @param last_resp [Faraday::Response] the most-recent raw response
-      # @param base_query [Hash] the original query hash
-      # @return [Hash, nil] options for the next page, or +nil+ to stop
-      def paginate_availability_page(acc, last_resp, base_query)
-        latest = last_resp.body
-
-        merge_availability_page(acc, latest) unless acc.equal?(latest)
-        availability_next_page_options(latest, base_query)
-      end
-
-      # Merges a new page body into the running accumulator.
-      #
-      # @param acc [Hash] the accumulator hash
-      # @param latest [Hash] the most-recent page body
-      # @return [void]
-      def merge_availability_page(acc, latest)
-        acc['availabilities'] = (acc['availabilities'] || []) + (latest['availabilities'] || [])
-        acc['total']          = (acc['total'] || 0) + (latest['total'] || 0)
-        acc['next_slot']      = latest['next_slot']
-      end
-
-      # Determines the options for the next page of availabilities, or +nil+
-      # if pagination should stop.
-      #
-      # @param latest [Hash] the most-recent page body
-      # @param base_query [Hash] the original query hash
-      # @return [Hash, nil] next-page options, or +nil+ to halt
-      def availability_next_page_options(latest, base_query)
-        avails        = latest['availabilities'] || []
-        last_date_str = avails.last&.dig('date')
-        return unless last_date_str && latest['next_slot']
-
-        next_start = (Date.parse(last_date_str) + 1).to_s
-        { query: base_query.merge(start_date: next_start) }
-      end
-    end
-  end
-end