toc_doc 1.0.0

data/lib/toc_doc/core/configurable.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require 'toc_doc/core/default'
+
+module TocDoc
+  # Mixin providing shared configuration behaviour for both the top-level
+  # {TocDoc} module and individual {TocDoc::Client} instances.
+  #
+  # Include this module to gain attribute accessors for every configurable key,
+  # a block-based {#configure} helper, and a {#reset!} method to restore
+  # defaults from {TocDoc::Default}.
+  #
+  # @example Module-level configuration
+  #   TocDoc.configure do |config|
+  #     config.api_endpoint = 'https://www.doctolib.de'
+  #     config.per_page     = 10
+  #   end
+  #
+  # @example Per-client configuration
+  #   client = TocDoc::Client.new(api_endpoint: 'https://www.doctolib.it')
+  #
+  # @see TocDoc::Default
+  module Configurable
+    # @return [Array<Symbol>] all recognised configuration keys
+    VALID_CONFIG_KEYS = %i[
+      api_endpoint
+      user_agent
+      middleware
+      connection_options
+      default_media_type
+      per_page
+      auto_paginate
+    ].freeze
+
+    # @!attribute [rw] api_endpoint
+    #   @return [String] the base URL for API requests
+    # @!attribute [rw] user_agent
+    #   @return [String] the User-Agent header value
+    # @!attribute [rw] middleware
+    #   @return [Faraday::RackBuilder, nil] custom Faraday middleware stack
+    # @!attribute [rw] connection_options
+    #   @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
+    # {TocDoc::Default::MAX_PER_PAGE}.
+    #
+    # @param value [Integer, #to_i] desired page size
+    # @return [Integer] the effective page size after clamping
+    def per_page=(value)
+      @per_page = [value.to_i, TocDoc::Default::MAX_PER_PAGE].min
+    end
+
+    # Returns the list of recognised configurable attribute names.
+    #
+    # @return [Array<Symbol>]
+    def self.keys
+      VALID_CONFIG_KEYS
+    end
+
+    # Yields +self+ so callers can set options in a block.
+    #
+    # @yield [config] the object being configured
+    # @yieldparam config [TocDoc::Configurable] self
+    # @return [self]
+    #
+    # @example
+    #   TocDoc.configure do |config|
+    #     config.api_endpoint = 'https://www.doctolib.de'
+    #   end
+    def configure
+      yield self
+      self
+    end
+
+    # Reset all configuration options to their {TocDoc::Default} values.
+    #
+    # @return [self]
+    def reset!
+      TocDoc::Default.options.each do |key, value|
+        public_send("#{key}=", value)
+      end
+      self
+    end
+
+    # Returns a frozen snapshot of the current configuration as a Hash.
+    #
+    # @return [Hash{Symbol => Object}]
+    def options
+      Configurable.keys.to_h { |key| [key, public_send(key)] }
+    end
+
+    # Compares the given options to the current configuration.
+    #
+    # Used internally for memoising the {TocDoc.client} instance — a new
+    # client is created only when the options have actually changed.
+    #
+    # @param other_options [Hash{Symbol => Object}] options to compare
+    # @return [Boolean] +true+ when both option sets are equal
+    def same_options?(other_options)
+      candidate =
+        if other_options.respond_to?(:to_hash)
+          other_options.to_hash.transform_keys!(&:to_sym)
+        else
+          other_options
+        end
+
+      candidate == options
+    end
+
+    # @!visibility private
+    # When extended (e.g., by the TocDoc module), initialize with defaults.
+    def self.extended(base)
+      base.reset!
+    end
+  end
+end

data/lib/toc_doc/core/connection.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module TocDoc
+  # Faraday-based HTTP connection and request helpers.
+  #
+  # Included into {TocDoc::Client} to provide low-level HTTP verbs
+  # (`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}).
+  #
+  # @see TocDoc::Client
+  module Connection
+    # The most-recent raw Faraday response, set after every request.
+    #
+    # @return [Faraday::Response, nil]
+    attr_accessor :last_response
+
+    private
+
+    # Perform a GET request.
+    #
+    # @param path [String] API path (relative to {Configurable#api_endpoint})
+    # @param options [Hash] query / header options forwarded to {#request}
+    # @return [Object] parsed response body
+    def get(path, options = {})
+      request(:get, path, nil, options)
+    end
+
+    # Perform a POST request.
+    #
+    # @param path [String] API path
+    # @param data [Object, nil] request body
+    # @param options [Hash] query / header options
+    # @return [Object] parsed response body
+    def post(path, data = nil, options = {})
+      request(:post, path, data, options)
+    end
+
+    # Perform a PUT request.
+    #
+    # @param path [String] API path
+    # @param data [Object, nil] request body
+    # @param options [Hash] query / header options
+    # @return [Object] parsed response body
+    def put(path, data = nil, options = {})
+      request(:put, path, data, options)
+    end
+
+    # Perform a PATCH request.
+    #
+    # @param path [String] API path
+    # @param data [Object, nil] request body
+    # @param options [Hash] query / header options
+    # @return [Object] parsed response body
+    def patch(path, data = nil, options = {})
+      request(:patch, path, data, options)
+    end
+
+    # Perform a DELETE request.
+    #
+    # @param path [String] API path
+    # @param options [Hash] query / header options
+    # @return [Object] parsed response body
+    def delete(path, options = {})
+      request(:delete, path, nil, options)
+    end
+
+    # Perform a HEAD request.
+    #
+    # @param path [String] API path
+    # @param options [Hash] query / header options
+    # @return [Object] parsed response body
+    def head(path, options = {})
+      request(:head, path, nil, options)
+    end
+
+    # Memoised Faraday connection configured from the current
+    # {Configurable} options.
+    #
+    # @return [Faraday::Connection]
+    def agent
+      @agent ||= Faraday.new(api_endpoint, faraday_options) do |conn|
+        configure_faraday_headers(conn)
+      end
+    end
+
+    # @return [Hash] merged Faraday connection options
+    def faraday_options
+      opts = connection_options.dup
+      opts[:builder] = middleware if middleware
+      opts
+    end
+
+    # Sets default HTTP headers on a Faraday connection.
+    #
+    # @param conn [Faraday::Connection]
+    # @return [void]
+    def configure_faraday_headers(conn)
+      conn.headers['Accept']       = default_media_type
+      conn.headers['Content-Type'] = default_media_type
+      conn.headers['User-Agent']   = user_agent
+    end
+
+    # Performs a paginated GET, accumulating results across pages.
+    #
+    # When {Configurable#auto_paginate} is disabled or no block is given,
+    # behaves exactly like {#get}.
+    #
+    # 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:
+    #
+    # 1. Detect whether it is a continuation call by comparing object identity:
+    #    `acc.equal?(last_response.body)` is `true` only on the first yield,
+    #    when the accumulator *is* the first-page body.  On subsequent yields
+    #    the block should merge `last_response.body` into `acc`.
+    # 2. Return a Hash of options to pass to the next {#get} call (pagination
+    #    continues), or `nil` / `false` to halt.
+    #
+    # @param path [String] the API path
+    # @param options [Hash] query / header options forwarded to every request
+    # @yieldparam acc [Object] the growing accumulator (first-page body initially)
+    # @yieldparam last_response [Faraday::Response] the most-recent raw response
+    # @yieldreturn [Hash, nil] next-page options, or +nil+/+false+ to halt
+    # @return [Object] the fully-accumulated response body
+    def paginate(path, options = {}, &)
+      data = get(path, options)
+      return data unless block_given? && auto_paginate
+
+      loop do
+        next_options = yield(data, last_response)
+        break unless next_options
+
+        get(path, next_options)
+      end
+
+      data
+    end
+
+    # Returns a boolean based on the HTTP response status of the given request.
+    #
+    # @param method [Symbol] HTTP verb (e.g. +:get+, +:head+)
+    # @param path [String] API path
+    # @param options [Hash] query / header options
+    # @return [Boolean] +true+ when the response is 2xx
+    def boolean_from_response?(method, path, options = {})
+      request(method, path, nil, options)
+      status = last_response&.status
+
+      (200..299).cover?(status)
+    end
+
+    # Core request helper used by all HTTP verb methods.
+    #
+    # @param method [Symbol] HTTP verb
+    # @param path [String] API path
+    # @param data [Object, nil] optional request body
+    # @param options [Hash] query / header options
+    # @return [Object] parsed response body
+    def request(method, path, data = nil, options = {})
+      query, headers = parse_query_and_convenience_headers(options)
+
+      response = agent.public_send(method) do |req|
+        req.url(path, query)
+        req.headers.update(headers) unless headers.empty?
+        req.body = data if data
+      end
+
+      self.last_response = response
+      response.body
+    end
+
+    # Splits a generic options hash into query params and headers.
+    #
+    # Supports explicit `:query` and `:headers` keys; otherwise treats
+    # remaining keys as query params.
+    #
+    # @param options [Hash] combined query/header options
+    # @return [Array(Hash, Hash)] a two-element array of `[query, headers]`
+    def parse_query_and_convenience_headers(options)
+      return [{}, {}] if options.nil? || options.empty?
+
+      opts = options.dup
+      explicit_query = opts.delete(:query)
+      explicit_headers = opts.delete(:headers) || {}
+
+      query = explicit_query || opts
+
+      [query || {}, explicit_headers]
+    end
+  end
+end

data/lib/toc_doc/core/default.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+
+require 'toc_doc/http/middleware/raise_error'
+
+module TocDoc
+  # Provides sensible default values for every configurable option.
+  #
+  # Each value can be overridden per-environment via the corresponding `TOCDOC_*`
+  # environment variable (see individual methods).
+  #
+  # @see TocDoc::Configurable
+  module Default
+    # @return [String] the default API base URL
+    API_ENDPOINT = 'https://www.doctolib.fr'
+
+    # @return [String] the default User-Agent header
+    USER_AGENT   = "TocDoc Ruby Gem #{TocDoc::VERSION}".freeze
+
+    # @return [String] the default Accept / Content-Type media type
+    MEDIA_TYPE   = 'application/json'
+
+    # @return [Integer] the default number of results per page
+    PER_PAGE       = 15
+
+    # @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
+
+    class << self
+      # Returns a hash of all default configuration values, suitable for
+      # passing to {TocDoc::Configurable#reset!}.
+      #
+      # @return [Hash{Symbol => Object}]
+      def options
+        {
+          api_endpoint: api_endpoint,
+          user_agent: user_agent,
+          default_media_type: default_media_type,
+          per_page: per_page,
+          auto_paginate: auto_paginate,
+          middleware: middleware,
+          connection_options: connection_options
+        }
+      end
+
+      # The base API endpoint URL.
+      #
+      # Falls back to the `TOCDOC_API_ENDPOINT` environment variable, then
+      # {API_ENDPOINT}.
+      #
+      # @return [String]
+      def api_endpoint
+        ENV.fetch('TOCDOC_API_ENDPOINT', API_ENDPOINT)
+      end
+
+      # The User-Agent header sent with every request.
+      #
+      # Falls back to the `TOCDOC_USER_AGENT` environment variable, then
+      # {USER_AGENT}.
+      #
+      # @return [String]
+      def user_agent
+        ENV.fetch('TOCDOC_USER_AGENT', USER_AGENT)
+      end
+
+      # The Accept / Content-Type media type.
+      #
+      # Falls back to the `TOCDOC_MEDIA_TYPE` environment variable, then
+      # {MEDIA_TYPE}.
+      #
+      # @return [String]
+      def default_media_type
+        ENV.fetch('TOCDOC_MEDIA_TYPE', MEDIA_TYPE)
+      end
+
+      # Number of results per page, clamped to {MAX_PER_PAGE}.
+      #
+      # Falls back to the `TOCDOC_PER_PAGE` environment variable, then
+      # {PER_PAGE}.
+      #
+      # @return [Integer]
+      def per_page
+        [Integer(ENV.fetch('TOCDOC_PER_PAGE', PER_PAGE), 10), MAX_PER_PAGE].min
+      rescue ArgumentError
+        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
+      # adapter.
+      #
+      # @return [Faraday::RackBuilder]
+      def middleware
+        @middleware ||= build_middleware
+      end
+
+      # Default Faraday connection options (empty by default).
+      #
+      # @return [Hash]
+      def connection_options
+        @connection_options ||= {}
+      end
+
+      private
+
+      def build_middleware
+        Faraday::RackBuilder.new do |builder|
+          builder.request :retry, retry_options
+          builder.use TocDoc::Middleware::RaiseError
+          builder.response :raise_error
+          builder.response :json, content_type: /\bjson$/
+          builder.adapter Faraday.default_adapter
+        end
+      end
+
+      def retry_options
+        {
+          max: Integer(ENV.fetch('TOCDOC_RETRY_MAX', MAX_RETRY), 10),
+          interval: 0.5,
+          interval_randomness: 0.5,
+          backoff_factor: 2,
+          retry_statuses: [429, 500, 502, 503, 504],
+          methods: %i[get head options]
+        }
+      rescue ArgumentError
+        retry_options_fallback
+      end
+
+      def retry_options_fallback
+        {
+          max: MAX_RETRY,
+          interval: 0.5,
+          interval_randomness: 0.5,
+          backoff_factor: 2,
+          retry_statuses: [429, 500, 502, 503, 504],
+          methods: %i[get head options]
+        }
+      end
+    end
+  end
+end

data/lib/toc_doc/core/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module TocDoc
+  # Base error class for all TocDoc errors.
+  #
+  # Inherits from +StandardError+ so consumers can rescue `TocDoc::Error`
+  # without any knowledge of Faraday or other internal HTTP details.
+  #
+  # @example Rescuing TocDoc errors
+  #   begin
+  #     TocDoc.availabilities(visit_motive_ids: 0, agenda_ids: 0)
+  #   rescue TocDoc::Error => e
+  #     puts e.message
+  #   end
+  class Error < StandardError; end
+end

data/lib/toc_doc/core/uri_utils.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module TocDoc
+  # URL building helpers for Doctolib API parameters.
+  #
+  # 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:
+  #
+  #   module TocDoc::Client::Availabilities
+  #     include TocDoc::UriUtils
+  #
+  #     def availabilities(visit_motive_ids:, agenda_ids:, **opts)
+  #       get('/availabilities.json', query: {
+  #         visit_motive_ids: dashed_ids(visit_motive_ids),
+  #         agenda_ids:       dashed_ids(agenda_ids),
+  #         **opts
+  #       })
+  #     end
+  #   end
+  module UriUtils
+    # Joins one or many IDs into the dash-separated format expected by Doctolib.
+    #
+    # @param ids [Integer, String, Array] one or more IDs
+    # @return [String] e.g. "1234-5678-9012"
+    def dashed_ids(ids)
+      Array(ids).flatten.compact.map(&:to_s).reject(&:empty?).join('-')
+    end
+  end
+end

data/lib/toc_doc/core/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module TocDoc
+  # The current version of the TocDoc gem.
+  #
+  # @return [String]
+  VERSION = '1.0.0'
+end

data/lib/toc_doc/http/middleware/raise_error.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module TocDoc
+  # @api private
+  module Middleware
+    # Faraday middleware that translates Faraday HTTP errors into
+    # {TocDoc::Error}, keeping Faraday as an internal implementation detail.
+    #
+    # Registered in the default middleware stack built by {TocDoc::Default}.
+    #
+    # @see TocDoc::Error
+    class RaiseError < Faraday::Middleware
+      # Executes the request and re-raises any +Faraday::Error+ as a
+      # {TocDoc::Error}.
+      #
+      # @param env [Faraday::Env] the Faraday request environment
+      # @return [Faraday::Env] the response environment on success
+      # @raise [TocDoc::Error] when Faraday raises an HTTP error
+      def call(env)
+        @app.call(env)
+      rescue Faraday::Error => e
+        raise TocDoc::Error, e.message
+      end
+    end
+  end
+end

data/lib/toc_doc/http/response/base_middleware.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+module TocDoc
+  # @api private
+  module Response
+    # Abstract base class for TocDoc Faraday response middleware.
+    #
+    # Subclasses **must** override {#on_complete} to inspect or transform
+    # the response environment.
+    #
+    # @abstract
+    class BaseMiddleware < Faraday::Middleware
+      # Called by Faraday after the response has been received.
+      #
+      # @param env [Faraday::Env] the Faraday response environment
+      # @return [void]
+      # @raise [NotImplementedError] always — subclasses must override
+      def on_complete(env)
+        raise NotImplementedError, "#{self.class} must implement #on_complete"
+      end
+    end
+  end
+end

data/lib/toc_doc/models/availability.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+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"]
+  class Availability < Resource
+    # @return [String] date in ISO 8601 format (e.g. "2026-02-28")
+    def date
+      @attrs['date']
+    end
+
+    # @return [Array<String>] ISO 8601 datetime strings for each available slot
+    def slots
+      @attrs['slots'] || []
+    end
+  end
+end

data/lib/toc_doc/models/resource.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module TocDoc
+  # A lightweight wrapper providing dot-notation access to response fields.
+  # Backed by a Hash, with +method_missing+ for attribute access and +#to_h+ for
+  # round-tripping back to a plain Hash.
+  #
+  # Unlike Sawyer, TocDoc does not use hypermedia relations, so this wrapper
+  # intentionally stays minimal.
+  #
+  # @example
+  #   resource = TocDoc::Resource.new('date' => '2026-02-28', 'slots' => [])
+  #   resource.date   #=> "2026-02-28"
+  #   resource[:date] #=> "2026-02-28"
+  #   resource.to_h   #=> { "date" => "2026-02-28", "slots" => [] }
+  class Resource
+    # @param attrs [Hash] the raw attribute hash (string or symbol keys)
+    def initialize(attrs = {})
+      @attrs = attrs.transform_keys(&:to_s)
+    end
+
+    # Read an attribute by name.
+    #
+    # @param key [String, Symbol] attribute name
+    # @return [Object, nil] the attribute value, or +nil+ if not present
+    #
+    # @example
+    #   resource[:date] #=> "2026-02-28"
+    def [](key)
+      @attrs[key.to_s]
+    end
+
+    # Write an attribute by name.
+    #
+    # @param key [String, Symbol] attribute name
+    # @param value [Object] the value to set
+    # @return [Object] the value
+    def []=(key, value)
+      @attrs[key.to_s] = value
+    end
+
+    # Return a plain Hash representation (shallow copy).
+    #
+    # @return [Hash{String => Object}]
+    def to_h
+      @attrs.dup
+    end
+
+    # Equality comparison.
+    #
+    # Two {Resource} instances are equal when their attribute hashes match.
+    # A {Resource} is also equal to a plain +Hash+ with equivalent keys.
+    #
+    # @param other [Resource, Hash, Object]
+    # @return [Boolean]
+    def ==(other)
+      case other
+      when Resource then @attrs == other.to_h
+      when Hash     then @attrs == other.transform_keys(&:to_s)
+      else false
+      end
+    end
+
+    # @!visibility private
+    def respond_to_missing?(method_name, include_private = false)
+      @attrs.key?(method_name.to_s) || super
+    end
+
+    # Provides dot-notation access to response fields.
+    #
+    # Any method call whose name matches a key in the underlying attribute
+    # hash is dispatched here.
+    #
+    # @param method_name [Symbol] the method name
+    # @return [Object] the attribute value
+    # @raise [NoMethodError] when the key does not exist
+    def method_missing(method_name, *_args)
+      key = method_name.to_s
+      @attrs.key?(key) ? @attrs[key] : super
+    end
+  end
+end