toc_doc 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3637aae8586b1ea3b5b568a4ef64a295b3e3664ada7d252163e8176ce429aa37
-  data.tar.gz: da283d2f5efd9c37b7f6b20d6bc207dcb79f826850b8d7d0953157473f36345f
+  metadata.gz: dcac91743cd8f8d50d032638c3a690f88c786a369960d8b5df8bdead6006149c
+  data.tar.gz: d8df90b16b2ff3e2311af4751396ff1ae54173575e4507989df0e7c910bd82eb
 SHA512:
-  metadata.gz: 79a3d614929d14b5709dec397ab39a78c07db2db0e31da2e2de7423af8da4a1af5b5dbc77f3943da8b104ab25b85531328e739697384fb7a8a53451320bf9951
-  data.tar.gz: 962d1c35bb6ede7899491b93e0f00c868a3aa87ffe4a32b076576b0017d96ff09e3214eb37000bee0ba40f43269597c75d21daf18c77e92787b39d61b29b4696
+  metadata.gz: e8886203725b1dd9bbd59e62ee56aaf4f0965c908b31d478568c9d0149a7062f7059509f5692f18273e08b4a05d90d8a6d6e8bb02e89342ab2d1a18e92b2b16a
+  data.tar.gz: fd9271676246e8da0e7e626ebc3c10316f5b86b2ab6fc811a67986bb276aa1e817c74f7d17fec64372cfb15048638b1aac32e08b2dce981142646ed4a1289977

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 ## [Unreleased]
 
+## [1.2.0] - 2026-03-08
+
+### Added
+
+- **`TocDoc::Availability::Collection`** — new `Enumerable` collection class returned by `TocDoc::Availability.where`; provides `#total`, `#next_slot`, `#each`, `#raw_availabilities`, `#to_h`, and `#merge_page!`
+- **`TocDoc::Availability.where`** — class-level query method replacing `Client#availabilities`; automatically follows a `next_slot` response key with a second request before returning the collection
+- **`TocDoc.availabilities`** — top-level shortcut delegating to `TocDoc::Availability.where`
+- **Dependabot** — automated Bundler dependency updates via `.github/dependabot.yml`
+
+### Changed
+
+- **Connection** — `#get` and `#paginate` are now public on `TocDoc::Connection`, allowing model classes to call them directly via `TocDoc.client`
+- **`TocDoc::UriUtils`** — updated module-level example to reflect actual usage (`TocDoc::Availability` with `extend`, not the removed `Client::Availabilities`)
+
+### Removed
+
+- **`TocDoc::Client::Availabilities`** — endpoint module removed; availability querying now lives in `TocDoc::Availability.where` and `TocDoc::Availability::Collection`
+- **`TocDoc::Response::Availability`** — response wrapper model removed; replaced by `TocDoc::Availability::Collection`
+- **`auto_paginate`** — configuration key, default, and all related logic removed from `TocDoc::Configurable` and `TocDoc::Default`
+
+## [1.1.0] - 2026-03-06
+
+### Changed
+
+- **`TocDoc::Availability`** — `#date` now returns a parsed `Date` object instead of a raw string; `#slots` now returns an array of `DateTime` objects instead of strings
+- **`TocDoc::Response::Availability#next_slot`** — falls back to inferring the next slot from the first available slot when the API response omits the `next_slot` key
+
+### Removed
+
+- **VCR** — removed VCR dependency from the test suite; HTTP interactions are now stubbed directly with WebMock
+
 ## [1.0.0] - 2026-03-04
 
 ### Added

data/POTENTIAL_ENDPOINTS.md

@@ -0,0 +1,31 @@
+# Potential Endpoints
+
+- Interesting JSONs [GET]
+  - [x] Availabilities
+    - https://www.doctolib.fr/availabilities.json?visit_motive_ids=7767829&agenda_ids=1101600&practice_ids=377272&telehealth=false&start_date=2026-03-06&limit=5
+  - Practitioner ? 
+    - https://www.doctolib.fr/pharmacie/paris/pharmacie-faidherbe.json
+    - https://www.doctolib.fr/dentiste/bordeaux/mathilde-devun-lesparre-medoc.json
+    - https://www.doctolib.fr/a/b/mathilde-devun-lesparre-medoc.json
+    - https://www.doctolib.fr/profiles/mathilde-devun-lesparre-medoc.json
+  - Rassemblement practiciens / Place Practitioners collection
+    - https://www.doctolib.fr/profiles/pavillon-de-la-mutualite-bordeaux-rue-vital-carles.json
+  - Places
+    - https://www.doctolib.fr/patient_app/place_autocomplete.json?query=47300
+  - Booking context
+    - https://www.doctolib.fr/online_booking/api/slot_selection_funnel/v1/info.json?profile_slug=brigitte-devun-pujols&locale=fr
+    - https://www.doctolib.fr/online_booking/api/slot_selection_funnel/v1/info.json?profile_slug=926388&locale=fr
+- Interesting NON JSONs
+  - City practitioners (❗️JSON-LD in a script tag of an HTML page - data-id="removable-json-ld")
+    - https://www.doctolib.fr/dentiste/bordeaux/
+    - https://www.doctolib.fr/medecin-generaliste/bordeaux/
+    - https://www.doctolib.fr/medecin-generaliste/villeneuve-sur-lot
+- Non-interesting 
+  - Legal links
+    - https://www.doctolib.fr/search/footer_legal_links.json
+  - FAQ
+    - https://www.doctolib.fr/search/footer_public_content.json?hub_search=false&display_faq=true&speciality_id=2&place_id=18733 
+  - Social media links
+    - https://www.doctolib.fr/search/footer_social_media_links.json
+  - New Booking [POST]
+    - online_booking/draft/new.json

data/README.md

@@ -1,6 +1,12 @@
 # TocDoc
 
-A Ruby gem for interacting with the (unofficial) Doctolib API. A thin, Faraday-based client with modular resource endpoints, configurable defaults, optional auto-pagination, and a clean error hierarchy.
+A Ruby gem for interacting with the (unofficial) Doctolib API. A thin, Faraday-based client with configurable defaults, model-driven resource querying, and a clean error hierarchy.
+
+[![Gem Version](https://badge.fury.io/rb/toc_doc.svg)](https://badge.fury.io/rb/toc_doc)
+[![CI](https://github.com/01max/toc_doc/actions/workflows/main.yml/badge.svg)](https://github.com/01max/toc_doc/actions)
+[![Coverage Status](https://coveralls.io/repos/github/01max/toc_doc/badge.svg?branch=main)](https://coveralls.io/github/01max/toc_doc?branch=main)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![YARD Docs](https://img.shields.io/badge/docs-YARD-blue.svg)](https://rubydoc.info/gems/toc_doc)
 
 > **Heads-up:** Doctolib™ does not publish a public API. This gem reverse-engineers
 > the endpoints used by the Doctolib™ website. Behaviour may change at any time
@@ -59,19 +65,18 @@ gem install toc_doc
 ```ruby
 require 'toc_doc'
 
-# Use the pre-configured module-level client …
-response = TocDoc.availabilities(
+collection = TocDoc::Availability.where(
   visit_motive_ids: 7_767_829,
   agenda_ids:       1_101_600,
   practice_ids:     377_272,
   telehealth:       false
 )
 
-response.total      # => 5
-response.next_slot  # => "2026-02-28T10:00:00.000+01:00"
+collection.total      # => 5
+collection.next_slot  # => "2026-02-28T10:00:00.000+01:00"
 
-response.availabilities.each do |avail|
-  puts "#{avail.date}: #{avail.slots.join(', ')}"
+collection.each do |avail|
+  puts "#{avail.date}: #{avail.slots.map { |s| s.strftime('%H:%M') }.join(', ')}"
 end
 ```
 
@@ -89,7 +94,7 @@ TocDoc.configure do |config|
   config.per_page     = 10
 end
 
-TocDoc.availabilities(visit_motive_ids: 123, agenda_ids: 456)
+TocDoc::Availability.where(visit_motive_ids: 123, agenda_ids: 456)
 ```
 
 Calling `TocDoc.reset!` restores all options to their defaults.  
@@ -97,14 +102,24 @@ Use `TocDoc.options` to inspect the current configuration hash.
 
 ### Per-client configuration
 
-Instantiate independent clients with different options:
+Instantiate independent clients with different options and query via `TocDoc::Availability.where`:
 
 ```ruby
-de_client = TocDoc::Client.new(api_endpoint: 'https://www.doctolib.de')
-it_client = TocDoc::Client.new(api_endpoint: 'https://www.doctolib.it', per_page: 3)
+# Germany
+TocDoc.configure { |c| c.api_endpoint = 'https://www.doctolib.de'; c.per_page = 3 }
+TocDoc::Availability.where(visit_motive_ids: 123, agenda_ids: 456)
+
+# Reset and switch to Italy
+TocDoc.reset!
+TocDoc.configure { |c| c.api_endpoint = 'https://www.doctolib.it' }
+TocDoc::Availability.where(visit_motive_ids: 789, agenda_ids: 101)
+```
 
-de_client.availabilities(visit_motive_ids: 123, agenda_ids: 456)
-it_client.availabilities(visit_motive_ids: 789, agenda_ids: 101)
+Alternatively, use `TocDoc::Client` directly for lower-level access ().
+
+```ruby
+client = TocDoc::Client.new(api_endpoint: 'https://www.doctolib.de', per_page: 5)
+client.get('/availabilities.json', query: { visit_motive_ids: '123', agenda_ids: '456', start_date: Date.today.to_s, limit: 5 })
 ```
 
 ### All configuration options
@@ -112,10 +127,9 @@ it_client.availabilities(visit_motive_ids: 789, agenda_ids: 101)
 | Option | Default | Description |
 |---|---|---|
 | `api_endpoint` | `https://www.doctolib.fr` | Base URL. Change to `.de` / `.it` for other countries. |
-| `user_agent` | `TocDoc Ruby Gem 0.1.0` | `User-Agent` header sent with every request. |
+| `user_agent` | `TocDoc Ruby Gem 1.2.0` | `User-Agent` header sent with every request. |
 | `default_media_type` | `application/json` | `Accept` and `Content-Type` headers. |
-| `per_page` | `5` | Default number of results returned per request, platform's max is currently at `15`. |
-| `auto_paginate` | `false` | When `true`, automatically fetches all pages and merges results. |
+| `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. |
 | `connection_options` | `{}` | Options passed directly to `Faraday.new`. |
 
@@ -129,7 +143,6 @@ All primary options can be set via environment variables before the gem is loade
 | `TOCDOC_USER_AGENT` | `user_agent` |
 | `TOCDOC_MEDIA_TYPE` | `default_media_type` |
 | `TOCDOC_PER_PAGE` | `per_page` |
-| `TOCDOC_AUTO_PAGINATE` | `auto_paginate` (`"true"` / anything else) |
 | `TOCDOC_RETRY_MAX` | Maximum Faraday retry attempts (default `3`) |
 
 ---
@@ -141,7 +154,7 @@ All primary options can be set via environment variables before the gem is loade
 Retrieve open appointment slots for a given visit motive and agenda.
 
 ```ruby
-client.availabilities(
+TocDoc::Availability.where(
   visit_motive_ids: visit_motive_id,   # Integer, String, or Array
   agenda_ids:       agenda_id,         # Integer, String, or Array
   start_date:       Date.today,        # Date or String (default: today)
@@ -152,18 +165,20 @@ client.availabilities(
 )
 ```
 
+`TocDoc.availabilities(...)` is a module-level shortcut with the same signature.
+
 **Multiple IDs** are accepted as arrays; the gem serialises them with the
 dash-separated format Doctolib expects:
 
 ```ruby
-client.availabilities(
+TocDoc::Availability.where(
   visit_motive_ids: [7_767_829, 7_767_830],
   agenda_ids:       [1_101_600, 1_101_601]
 )
 # → GET /availabilities.json?visit_motive_ids=7767829-7767830&agenda_ids=1101600-1101601&…
 ```
 
-**Return value:** a `TocDoc::Response::Availability` (see [Response objects](#response-objects)).
+**Return value:** a `TocDoc::Availability::Collection` (see [Response objects](#response-objects)).
 
 ---
 
@@ -172,39 +187,41 @@ client.availabilities(
 All API responses are wrapped in lightweight Ruby objects that provide
 dot-notation access and a `#to_h` round-trip helper.
 
-### `TocDoc::Response::Availability`
+### `TocDoc::Availability::Collection`
 
-Returned by `#availabilities`.
+Returned by `TocDoc::Availability.where`; also accessible via the `TocDoc.availabilities` module-level shortcut.
+Implements `Enumerable`, yielding `TocDoc::Availability` instances that have at least one slot.
 
 | Method | Type | Description |
 |---|---|---|
 | `#total` | `Integer` | Total number of available slots across all dates. |
 | `#next_slot` | `String \| nil` | ISO 8601 datetime of the nearest available slot. `nil` when none remain. |
-| `#availabilities` | `Array<TocDoc::Availability>` | One entry per date. |
-| `#to_h` | `Hash` | Plain-hash representation including expanded availability entries. |
+| `#each` | — | Yields each `TocDoc::Availability` that has at least one slot (excludes empty-slot dates). |
+| `#raw_availabilities` | `Array<TocDoc::Availability>` | All date entries, including those with no slots. |
+| `#to_h` | `Hash` | Plain-hash representation (only dates with slots in the `availabilities` key). |
 
 ### `TocDoc::Availability`
 
-Each element of `Response::Availability#availabilities`.
+Represents a single availability date entry. Each element yielded by the collection.
 
 | Method | Type | Description |
 |---|---|---|
-| `#date` | `String` | Date in `YYYY-MM-DD` format. |
-| `#slots` | `Array<String>` | ISO 8601 datetimes for each bookable slot on that date. |
+| `#date` | `Date` | Parsed date object. |
+| `#slots` | `Array<DateTime>` | Parsed datetime objects for each bookable slot on that date. |
 | `#to_h` | `Hash` | Plain-hash representation. |
 
 **Example:**
 
 ```ruby
-response = TocDoc.availabilities(visit_motive_ids: 123, agenda_ids: 456)
+collection = TocDoc::Availability.where(visit_motive_ids: 123, agenda_ids: 456)
 
-response.total      # => 5
-response.next_slot  # => "2026-02-28T10:00:00.000+01:00"
+collection.total      # => 5
+collection.next_slot  # => "2026-02-28T10:00:00.000+01:00"
 
-response.availabilities.first.date   # => "2026-02-28"
-response.availabilities.first.slots  # => ["2026-02-28T10:00:00.000+01:00", ...]
+collection.first.date   # => #<Date: 2026-02-28>
+collection.first.slots  # => [#<DateTime: 2026-02-28T10:00:00+01:00>, ...]
 
-response.to_h
+collection.to_h
 # => {
 #      "total"          => 5,
 #      "next_slot"      => "2026-02-28T10:00:00.000+01:00",
@@ -216,35 +233,36 @@ response.to_h
 
 ## Pagination
 
-The Doctolib availability endpoint is paginated by `start_date` and `limit`.
-TocDoc can manage this automatically.
+The Doctolib availability endpoint is window-based: each request returns up to
+`limit` dates starting from `start_date`.
 
-### Automatic pagination
+### Automatic next-slot resolution
 
-Set `auto_paginate: true` on the client (or at module level) to fetch all pages
-and have results merged into a single `Response::Availability` object:
+`TocDoc::Availability.where` automatically follows `next_slot` once: if the
+first API response contains a `next_slot` key (indicating no available slots in
+the requested window), a second request is issued transparently from that date
+before the collection is returned.
 
-```ruby
-client = TocDoc::Client.new(auto_paginate: true, per_page: 5)
+### Manual window advancement
 
-all_slots = client.availabilities(
+To fetch additional date windows, call `TocDoc::Availability.where` again with a
+later `start_date`:
+
+```ruby
+first_page = TocDoc::Availability.where(
   visit_motive_ids: 7_767_829,
   agenda_ids:       1_101_600,
   start_date:       Date.today
 )
 
-all_slots.total             # total across every page
-all_slots.availabilities    # every date entry, concatenated
-```
-
-Pagination stops automatically when the API returns `next_slot: null`.
-
-### Module-level toggle
-
-```ruby
-TocDoc.configure { |c| c.auto_paginate = true }
-
-TocDoc.availabilities(visit_motive_ids: 123, agenda_ids: 456)
+if first_page.any?
+  next_start = first_page.raw_availabilities.last.date + 1
+  next_page  = TocDoc::Availability.where(
+    visit_motive_ids: 7_767_829,
+    agenda_ids:       1_101_600,
+    start_date:       next_start
+  )
+end
 ```
 
 ---
@@ -256,7 +274,7 @@ so you can rescue the whole hierarchy with a single clause:
 
 ```ruby
 begin
-  TocDoc.availabilities(visit_motive_ids: 0, agenda_ids: 0)
+  TocDoc::Availability.where(visit_motive_ids: 0, agenda_ids: 0)
 rescue TocDoc::Error => e
   puts "Doctolib error: #{e.message}"
 end
@@ -313,13 +331,14 @@ bundle exec rake install
 
 ### Adding new endpoints
 
-1. Create `lib/toc_doc/client/<resource>.rb` and define a module
-   `TocDoc::Client::<Resource>` with your endpoint methods.
-2. Call `get`/`post`/`paginate` (from `TocDoc::Connection`) to issue requests.
-3. Create `lib/toc_doc/models/response/<resource>.rb` (and any model classes)
-   inheriting from `TocDoc::Resource`.
-4. Include the new module in `TocDoc::Client` (`lib/toc_doc/client.rb`).
-5. Add corresponding specs under `spec/toc_doc/client/`.
+1. Create `lib/toc_doc/models/<resource>.rb` with a model class inheriting from
+   `TocDoc::Resource`. Add a class-level `.where` (or equivalent) query method
+   that calls `TocDoc.client.get` / `.post` to issue requests.
+2. If the endpoint is paginated, create
+   `lib/toc_doc/models/<resource>/collection.rb` with an `Enumerable` collection
+   class (see `TocDoc::Availability::Collection` for the pattern).
+3. Require the new files from `lib/toc_doc/models.rb`.
+4. Add specs under `spec/toc_doc/models/`.
 
 ### Generating documentation
 

data/TODO.md

@@ -1,77 +1,100 @@
-# 1.0
+# PLAN
 
-## 1 – Skeleton & Tooling
+[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
+  - https://www.doctolib.fr/online_booking/api/slot_selection_funnel/v1/info.json?profile_slug=926388
+
+## 1.6
+
+### Better API usage
+- [ ] Rate limiting
+- [ ] Caching
+- [ ] Logging
+
+## 2.0
+
+### Auth / User-based actions
+- [ ] Research auth scheme
+- [ ] Authentication module + headers
+- [ ] Auth specs
+
+# DONE & RELEASED
+
+## 1.0
+
+### 1 – Skeleton & Tooling
 - [x] Scaffold gem & layout
 - [x] Gem spec metadata & deps
 - [x] Lib structure (default/config/client/etc.)
 - [x] CI workflow (RSpec + RuboCop)
 - [x] RSpec + WebMock + VCR setup
 
-## 2 – Configuration
+### 2 – Configuration
 - [x] Default options & ENV fallbacks
 - [x] Configurable module (keys, reset, options)
 - [x] Top-level TocDoc wiring (client, setup, delegation)
 - [x] Config specs (module + client)
 
-## 3 – Connection & HTTP
+### 3 – Connection & HTTP
 - [x] Connection module (agent, request helpers)
 - [x] ~Faraday middleware~
 - [x] URL building helpers
 - [x] Connection specs
 
-## 4 – Error Handling
+### 4 – Error Handling
 - [x] Error base class & factory
 - [x] Error subclasses (4xx/5xx)
 - [x] RaiseError middleware
 - [x] Error mapping specs
 
-## 5 – Client & Availabilities
+### 5 – Client & Availabilities
 - [x] Client includes config + connection
 - [x] Availabilities endpoint module
 - [x] TocDoc.availabilities delegation
 - [x] Availabilities specs (stubs/VCR)
 
-## 6 – Response Objects
+### 6 – Response Objects
 - [x] Resource wrapper
 - [x] Availability objects
 - [x] Client mapping to response objects
 - [x] Response specs
 
-## 8 – Pagination
+### 8 – Pagination
 - [x] Analyze pagination model
 - [x] Implement Connection#paginate
 - [x] Pagination config & specs
 
-## 9 – Docs & Release
+### 9 – Docs & Release
 - [x] README
 - [x] YARD docs
 - [x] CHANGELOG
 - [x] FIX GH CI
-- [ ] Build & publish gem 
-  - [ ] on rubygem
-  - [ ] gem.coop ?
-
-# 1.1
+- [x] Build & publish gem
+  - [x] on rubygem
+  - [x] release on GH
+  - [x] gem.coop/@maxime
+- [x] Add test coverage tool
 
-## Parse raw API data
-- [ ] Parse date / datetime
-- [ ] ?
+## 1.1
 
-## Better API usage
-- [ ] Rate limiting
-- [ ] Caching
-- [ ] Logging
-- [ ] Better multi-region support ?
-- [ ] Async support ?
+### Parse raw API data
+- [x] Parse date / datetime
 
-## Extra Endpoints
-- [ ] Identify additional endpoints
-- [ ] Implement resource modules
-- [ ] Specs per endpoint
+## 1.2
 
-# 1.2
-
-## Auth / User-based actions
-- [ ] Research auth scheme
-- [ ] Authentication module + headers
-- [ ] Auth specs
+- [x] Rework Availability's client, model and collection architecture.

data/lib/toc_doc/client.rb

@@ -3,7 +3,6 @@
 require 'toc_doc/core/configurable'
 require 'toc_doc/core/connection'
 require 'toc_doc/core/uri_utils'
-require 'toc_doc/client/availabilities'
 
 module TocDoc
   # The main entry-point for interacting with the Doctolib API.
@@ -16,18 +15,14 @@ module TocDoc
   #     api_endpoint: 'https://www.doctolib.de',
   #     per_page: 5
   #   )
-  #   client.availabilities(visit_motive_ids: 123, agenda_ids: 456)
   #
   # @see TocDoc::Configurable
   # @see TocDoc::Connection
-  # @see TocDoc::Client::Availabilities
   class Client
     include TocDoc::Configurable
     include TocDoc::Connection
     include TocDoc::UriUtils
 
-    include TocDoc::Client::Availabilities
-
     # Creates a new client instance.
     #
     # Options are merged on top of the module-level {TocDoc::Default} values.
@@ -39,7 +34,6 @@ module TocDoc
     # @option options [String]  :user_agent         User-Agent header value
     # @option options [String]  :default_media_type Accept / Content-Type header
     # @option options [Integer] :per_page           Results per page
-    # @option options [Boolean] :auto_paginate      Follow pagination automatically
     # @option options [Faraday::RackBuilder] :middleware Custom Faraday middleware
     # @option options [Hash]    :connection_options Additional Faraday options
     #

data/lib/toc_doc/core/configurable.rb

@@ -29,7 +29,6 @@ module TocDoc
       connection_options
       default_media_type
       per_page
-      auto_paginate
     ].freeze
 
     # @!attribute [rw] api_endpoint
@@ -42,8 +41,6 @@ module TocDoc
     #   @return [Hash] additional Faraday connection options
     # @!attribute [rw] default_media_type
     #   @return [String] the Accept / Content-Type header value
-    # @!attribute [rw] auto_paginate
-    #   @return [Boolean] whether to follow pagination automatically
     attr_accessor(*VALID_CONFIG_KEYS)
 
     # Set the number of results per page, clamped to

data/lib/toc_doc/core/connection.rb

@@ -9,8 +9,9 @@ module TocDoc
   # (`get`, `post`, `put`, `patch`, `delete`, `head`), a memoised
   # Faraday connection, pagination support, and response tracking.
   #
-  # All HTTP methods are **private** — callers interact with them through
-  # higher-level endpoint modules (e.g. {TocDoc::Client::Availabilities}).
+  # {#get} and {#paginate} are public so that model classes (e.g.
+  # {TocDoc::Availability}) can call them via `TocDoc.client`; all other
+  # HTTP verb methods remain private.
   #
   # @see TocDoc::Client
   module Connection
@@ -107,12 +108,11 @@ module TocDoc
 
     # Performs a paginated GET, accumulating results across pages.
     #
-    # When {Configurable#auto_paginate} is disabled or no block is given,
-    # behaves exactly like {#get}.
+    # Behaves exactly like {#get} when no block is given.
     #
-    # When +auto_paginate+ is +true+ **and** a block is provided, the block is
-    # yielded after every page fetch — including the first — with
-    # +(accumulator, last_response)+.  The block must:
+    # When a block is provided, it is yielded after every page fetch —
+    # including the first — with +(accumulator, last_response)+.  The block
+    # must:
     #
     # 1. Detect whether it is a continuation call by comparing object identity:
     #    `acc.equal?(last_response.body)` is `true` only on the first yield,
@@ -129,7 +129,7 @@ module TocDoc
     # @return [Object] the fully-accumulated response body
     def paginate(path, options = {}, &)
       data = get(path, options)
-      return data unless block_given? && auto_paginate
+      return data unless block_given?
 
       loop do
         next_options = yield(data, last_response)
@@ -192,5 +192,7 @@ module TocDoc
 
       [query || {}, explicit_headers]
     end
+
+    public :get, :paginate
   end
 end

data/lib/toc_doc/core/default.rb

@@ -28,9 +28,6 @@ module TocDoc
     # @return [Integer] the hard upper limit for per_page
     MAX_PER_PAGE   = 15
 
-    # @return [Boolean] whether to auto-paginate by default
-    AUTO_PAGINATE  = false
-
     # @return [Integer] the default maximum number of retries
     MAX_RETRY      = 3
 
@@ -45,7 +42,6 @@ module TocDoc
           user_agent: user_agent,
           default_media_type: default_media_type,
           per_page: per_page,
-          auto_paginate: auto_paginate,
           middleware: middleware,
           connection_options: connection_options
         }
@@ -93,19 +89,6 @@ module TocDoc
         PER_PAGE
       end
 
-      # Whether to follow pagination automatically.
-      #
-      # Falls back to the `TOCDOC_AUTO_PAGINATE` environment variable (set to
-      # `"true"` to enable), then {AUTO_PAGINATE}.
-      #
-      # @return [Boolean]
-      def auto_paginate
-        env_val = ENV.fetch('TOCDOC_AUTO_PAGINATE', nil)
-        return AUTO_PAGINATE if env_val.nil?
-
-        env_val.casecmp('true').zero?
-      end
-
       # The default Faraday middleware stack.
       #
       # Includes retry logic, error raising, JSON parsing, and the default

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.0.0'
+  VERSION = '1.2.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,21 +1,104 @@
 # 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.
   #
   # @example
   #   avail = TocDoc::Availability.new('date' => '2026-02-28', 'slots' => ['2026-02-28T10:00:00.000+01:00'])
-  #   avail.date   #=> "2026-02-28"
-  #   avail.slots  #=> ["2026-02-28T10:00:00.000+01:00"]
+  #   avail.date       #=> #<Date: 2026-02-28>
+  #   avail.raw_date   #=> "2026-02-28"
+  #   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
-    # @return [String] date in ISO 8601 format (e.g. "2026-02-28")
-    def date
-      @attrs['date']
+    extend TocDoc::UriUtils
+
+    attr_reader :date, :slots
+
+    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
 
-    # @return [Array<String>] ISO 8601 datetime strings for each available slot
-    def slots
-      @attrs['slots'] || []
+    # @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)
+
+      @date = Date.parse(raw['date']) if raw['date']
+      @slots = raw['slots'].map { |s| DateTime.parse(s) }
+    end
+
+    private
+
+    def build_raw(attrs)
+      {
+        'date' => attrs['date'],
+        'slots' => attrs['slots'] || []
+      }
     end
   end
 end

data/lib/toc_doc/models.rb

@@ -2,5 +2,4 @@
 
 require 'toc_doc/models/resource'
 require 'toc_doc/models/availability'
-
-require 'toc_doc/models/response/availability'
+require 'toc_doc/models/availability/collection'

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,16 @@ 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
+
     # @!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.0.0
+  version: 1.2.0
 platform: ruby
 authors:
 - 01max
@@ -45,7 +45,7 @@ dependencies:
         version: '2.0'
 description: |-
   A standalone Ruby gem providing a Faraday-based client
-      with modular resource endpoints, configurable defaults, and a clean error hierarchy.
+      to interact with the (unofficial) Doctolib API.
 email:
 - m.louguet@gmail.com
 executables: []
@@ -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,14 +75,13 @@ 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/resource.rb
-- lib/toc_doc/models/response/availability.rb
 - sig/toc_doc.rbs
 homepage: https://github.com/01max/toc_doc
 licenses:
 - GPL-3.0-or-later
 metadata:
-  allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/01max/toc_doc
   source_code_uri: https://github.com/01max/toc_doc/tree/main
   changelog_uri: https://github.com/01max/toc_doc/blob/main/CHANGELOG.md

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

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

@@ -1,79 +0,0 @@
-# frozen_string_literal: true
-
-module TocDoc
-  module Response
-    # Wraps the top-level response from the Doctolib availabilities API.
-    #
-    # @example
-    #   response = TocDoc::Response::Availability.new(parsed_json)
-    #   response.total          #=> 2
-    #   response.next_slot      #=> "2026-02-28T10:00:00.000+01:00"
-    #   response.availabilities #=> [#<TocDoc::Availability ...>, ...]
-    class Availability < Resource
-      # The total number of available slots across all dates.
-      #
-      # @return [Integer]
-      #
-      # @example
-      #   response.total #=> 5
-      def total
-        @attrs['total']
-      end
-
-      # The nearest available appointment slot.
-      #
-      # When the API includes an explicit +next_slot+ key (common when there
-      # are no slots in the loaded date window) that value is returned
-      # directly.  Otherwise the first slot of the first date that has one
-      # is returned.
-      #
-      # @return [String, nil] ISO 8601 datetime string, or +nil+ when no
-      #   slot is available
-      #
-      # @example
-      #   response.next_slot #=> "2026-02-28T10:00:00.000+01:00"
-      def next_slot
-        return @attrs['next_slot'] if @attrs.key?('next_slot')
-
-        Array(@attrs['availabilities']).each do |entry|
-          slots = Array(entry['slots'])
-          return slots.first unless slots.empty?
-        end
-
-        nil
-      end
-
-      # Dates that have at least one available slot, wrapped as
-      # {TocDoc::Availability} objects.
-      #
-      # @return [Array<TocDoc::Availability>]
-      #
-      # @example
-      #   response.availabilities.each do |avail|
-      #     puts "#{avail.date}: #{avail.slots.size} slot(s)"
-      #   end
-      def availabilities
-        @availabilities ||= Array(@attrs['availabilities'])
-                            .select { |entry| Array(entry['slots']).any? }
-                            .map { |entry| TocDoc::Availability.new(entry) }
-      end
-
-      # All availability date entries, including those with no slots.
-      #
-      # @return [Array<TocDoc::Availability>]
-      def raw_availabilities
-        @raw_availabilities ||= Array(@attrs['availabilities']).map do |entry|
-          TocDoc::Availability.new(entry)
-        end
-      end
-
-      # Returns a plain Hash representation, with nested +availabilities+
-      # expanded back to raw Hashes.
-      #
-      # @return [Hash{String => Object}]
-      def to_h
-        super.merge('availabilities' => availabilities.map(&:to_h))
-      end
-    end
-  end
-end