toc_doc 1.0.0

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

@@ -0,0 +1,79 @@
+# 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

data/lib/toc_doc/models.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'toc_doc/models/resource'
+require 'toc_doc/models/availability'
+
+require 'toc_doc/models/response/availability'

data/lib/toc_doc.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative 'toc_doc/core/version'
+
+require 'toc_doc/core/error'
+require 'toc_doc/core/configurable'
+require 'toc_doc/core/connection'
+require 'toc_doc/core/uri_utils'
+
+require 'toc_doc/models'
+
+require 'toc_doc/client'
+
+# The main module for TocDoc — a Ruby client for the Doctolib API.
+#
+# 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(
+#     visit_motive_ids: 7_767_829,
+#     agenda_ids: 1_101_600,
+#     practice_ids: 377_272
+#   )
+#
+# @see TocDoc::Configurable
+# @see TocDoc::Client
+module TocDoc
+  extend Configurable
+
+  class << self
+    # Returns a memoized {TocDoc::Client} configured with the current
+    # module-level options. A new client is created whenever the options
+    # have changed since the last call.
+    #
+    # @return [TocDoc::Client]
+    def client
+      if !defined?(@client) || @client.nil? || !@client.respond_to?(:same_options?) || !@client.same_options?(options)
+        @client = TocDoc::Client.new(options)
+      end
+      @client
+    end
+
+    # Allows replacing the current client instance.
+    #
+    # @param value [TocDoc::Client] a pre-configured client instance
+    # @return [TocDoc::Client]
+    attr_writer :client
+
+    # Configure TocDoc at the module level and return the client.
+    #
+    # @yield [config] yields self so options can be set in a block
+    # @yieldparam config [TocDoc] the module itself (responds to {Configurable} setters)
+    # @return [TocDoc::Client] the memoized client, reflecting the new configuration
+    #
+    # @example
+    #   TocDoc.setup do |config|
+    #     config.api_endpoint = 'https://www.doctolib.de'
+    #   end
+    def setup
+      yield self if block_given?
+      client
+    end
+
+    # @!visibility private
+    def method_missing(method_name, ...)
+      if client.respond_to?(method_name)
+        client.public_send(method_name, ...)
+      else
+        super
+      end
+    end
+
+    # @!visibility private
+    def respond_to_missing?(method_name, include_private = false)
+      client.respond_to?(method_name, include_private) || super
+    end
+  end
+end
+
+# Initialize module-level configuration on load.
+TocDoc.reset!

data/sig/toc_doc.rbs

@@ -0,0 +1,4 @@
+module TocDoc
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: toc_doc
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- 01max
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: |-
+  A standalone Ruby gem providing a Faraday-based client
+      with modular resource endpoints, configurable defaults, and a clean error hierarchy.
+email:
+- m.louguet@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.example"
+- ".yardopts"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.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
+- lib/toc_doc/core/default.rb
+- lib/toc_doc/core/error.rb
+- lib/toc_doc/core/uri_utils.rb
+- lib/toc_doc/core/version.rb
+- lib/toc_doc/http/middleware/raise_error.rb
+- lib/toc_doc/http/response/base_middleware.rb
+- lib/toc_doc/middleware/.keep
+- lib/toc_doc/models.rb
+- lib/toc_doc/models/availability.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
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: A Ruby gem to interact with the (unofficial) Doctolib API.
+test_files: []