api_adaptor 0.1.0 → 1.0.1

data/lib/api_adaptor/response.rb

@@ -4,65 +4,103 @@ require "json"
 require "forwardable"
 
 module ApiAdaptor
-  # This wraps an HTTP response with a JSON body.
+  # Wraps an HTTP response with a JSON body and provides convenient access methods.
   #
-  # Responses can be configured to use relative URLs for `web_url` properties.
-  # API endpoints should return absolute URLs so that they make sense outside of the
-  # domain context. However on systems within an API we want to present relative URLs.
-  # By specifying a base URI, this will convert all matching web_urls into relative URLs
+  # Response objects parse JSON and provide hash-like access to the response body.
+  # They also handle cache control headers and can convert absolute URLs to relative URLs.
   #
-  # Example:
+  # @example Basic usage
+  #   response = client.get_json("https://api.example.com/users")
+  #   users = response["results"]
+  #   cache_duration = response.cache_control.max_age
   #
-  #   r = Response.new(response, web_urls_relative_to: "https://www.example.com")
-  #   r['results'][0]['web_url']
-  #   => "/foo"
+  # @example With relative URLs
+  #   response = Response.new(http_response, web_urls_relative_to: "https://www.example.com")
+  #   response['results'][0]['web_url']  # => "/foo" instead of "https://www.example.com/foo"
+  #
+  # @example Checking cache headers
+  #   if response.cache_control.public? && response.cache_control.max_age > 300
+  #     # Cache this response
+  #   end
   class Response
     extend Forwardable
     include Enumerable
 
+    # Parses and provides access to HTTP Cache-Control header directives.
+    #
+    # @example
+    #   cc = CacheControl.new("public, max-age=3600, must-revalidate")
+    #   cc.public?          # => true
+    #   cc.max_age          # => 3600
+    #   cc.must_revalidate? # => true
     class CacheControl < Hash
+      # Regex pattern for parsing Cache-Control directives
       PATTERN = /([-a-z]+)(?:\s*=\s*([^,\s]+))?,?+/i
 
+      # Initializes a new CacheControl object by parsing a header value
+      #
+      # @param value [String, nil] Cache-Control header value
       def initialize(value = nil)
         super()
         parse(value)
       end
 
+      # @return [Boolean] true if cache is public
       def public?
         self["public"]
       end
 
+      # @return [Boolean] true if cache is private
       def private?
         self["private"]
       end
 
+      # @return [Boolean] true if no-cache directive is present
       def no_cache?
         self["no-cache"]
       end
 
+      # @return [Boolean] true if no-store directive is present
       def no_store?
         self["no-store"]
       end
 
+      # @return [Boolean] true if must-revalidate directive is present
       def must_revalidate?
         self["must-revalidate"]
       end
 
+      # @return [Boolean] true if proxy-revalidate directive is present
       def proxy_revalidate?
         self["proxy-revalidate"]
       end
 
+      # Returns the max-age directive value
+      #
+      # @return [Integer, nil] Maximum age in seconds, or nil if not present
       def max_age
         self["max-age"].to_i if key?("max-age")
       end
 
+      # Returns the r-maxage directive value
+      #
+      # Note: r-maxage is a non-standard Cache-Control directive and is not part
+      # of RFC 7234. This method exists for compatibility with custom cache implementations.
+      #
+      # @return [Integer, nil] Reverse maximum age in seconds, or nil if not present
       def reverse_max_age
         self["r-maxage"].to_i if key?("r-maxage")
       end
       alias r_maxage reverse_max_age
 
+      # Returns the s-maxage (shared max age) directive value
+      #
+      # The s-maxage directive is like max-age but only applies to shared caches
+      # (e.g., CDNs, proxies). It overrides max-age for shared caches.
+      #
+      # @return [Integer, nil] Shared maximum age in seconds, or nil if not present
       def shared_max_age
-        self["s-maxage"].to_i if key?("r-maxage")
+        self["s-maxage"].to_i if key?("s-maxage")
       end
       alias s_maxage shared_max_age
 
@@ -92,26 +130,67 @@ module ApiAdaptor
       end
     end
 
+    # @!method [](key)
+    #   Access parsed JSON response by key
+    #   @param key [String, Symbol] The key to access
+    #   @return [Object] The value at the key
+    #
+    # @!method <=>(other)
+    #   Compare responses
+    #   @param other [Response] Another response
+    #   @return [Integer] Comparison result
+    #
+    # @!method each(&block)
+    #   Iterate over parsed response hash
+    #   @yield [key, value] Each key-value pair
+    #
+    # @!method dig(*keys)
+    #   Dig into nested hash structure
+    #   @param keys [Array] Keys to traverse
+    #   @return [Object, nil] The value at the path or nil
     def_delegators :to_hash, :[], :"<=>", :each, :dig
 
+    # Initializes a new Response object
+    #
+    # @param http_response [RestClient::Response] The raw HTTP response
+    # @param options [Hash] Configuration options
+    # @option options [String] :web_urls_relative_to Base URL for converting absolute URLs to relative
+    #
+    # @example
+    #   response = Response.new(http_response)
+    #
+    # @example With relative URLs
+    #   response = Response.new(http_response, web_urls_relative_to: "https://www.example.com")
     def initialize(http_response, options = {})
       @http_response = http_response
       @web_urls_relative_to = options[:web_urls_relative_to] ? URI.parse(options[:web_urls_relative_to]) : nil
     end
 
+    # Returns the raw response body string
+    #
+    # @return [String] Raw response body
     def raw_response_body
       @http_response.body
     end
 
+    # Returns the HTTP status code
+    #
+    # @return [Integer] HTTP status code
     def code
       # Return an integer code for consistency with HTTPErrorResponse
       @http_response.code
     end
 
+    # Returns the response headers
+    #
+    # @return [Hash] HTTP headers
     def headers
       @http_response.headers
     end
 
+    # Calculates when the response expires based on cache headers
+    #
+    # @return [Time, nil] Expiration time or nil if not cacheable
     def expires_at
       if headers[:date] && cache_control.max_age
         response_date = Time.parse(headers[:date])
@@ -121,6 +200,9 @@ module ApiAdaptor
       end
     end
 
+    # Calculates how many seconds until the response expires
+    #
+    # @return [Integer, nil] Seconds until expiration or nil if not cacheable
     def expires_in
       return unless headers[:date]
 
@@ -133,22 +215,37 @@ module ApiAdaptor
       end
     end
 
+    # Returns parsed Cache-Control header
+    #
+    # @return [CacheControl] Parsed cache control directives
     def cache_control
       @cache_control ||= CacheControl.new(headers[:cache_control])
     end
 
+    # Returns the parsed JSON response as a hash
+    #
+    # @return [Hash] Parsed JSON response
     def to_hash
       parsed_content
     end
 
+    # Returns the parsed and transformed JSON content
+    #
+    # @return [Hash, Array] Parsed JSON with transformed web_urls
     def parsed_content
       @parsed_content ||= transform_parsed(JSON.parse(@http_response.body))
     end
 
+    # Always returns true (response is present)
+    #
+    # @return [Boolean] true
     def present?
       true
     end
 
+    # Always returns false (response is not blank)
+    #
+    # @return [Boolean] false
     def blank?
       false
     end

data/lib/api_adaptor/variables.rb

@@ -1,15 +1,52 @@
 # frozen_string_literal: true
 
 module ApiAdaptor
+  # Environment variable configuration for User-Agent metadata
+  #
+  # These variables are used to construct the User-Agent header for HTTP requests,
+  # allowing API providers to identify and contact clients if needed.
+  #
+  # @example Setting environment variables
+  #   ENV["APP_NAME"] = "MyApiClient"
+  #   ENV["APP_VERSION"] = "2.1.0"
+  #   ENV["APP_CONTACT"] = "dev@example.com"
+  #
+  # @example User-Agent header format
+  #   # "MyApiClient/2.1.0 (dev@example.com)"
+  #
+  # @see JSONClient.default_request_headers
   module Variables
+    # Returns the application name from environment variable
+    #
+    # @return [String] Application name (default: "Ruby ApiAdaptor App")
+    #
+    # @example
+    #   ENV["APP_NAME"] = "WikidataClient"
+    #   Variables.app_name  # => "WikidataClient"
     def self.app_name
       ENV["APP_NAME"] || "Ruby ApiAdaptor App"
     end
 
+    # Returns the application version from environment variable
+    #
+    # @return [String] Application version (default: "Version not stated")
+    #
+    # @example
+    #   ENV["APP_VERSION"] = "3.2.1"
+    #   Variables.app_version  # => "3.2.1"
     def self.app_version
       ENV["APP_VERSION"] || "Version not stated"
     end
 
+    # Returns the application contact from environment variable
+    #
+    # Should be an email address or URL where API providers can reach you.
+    #
+    # @return [String] Contact information (default: "Contact not stated")
+    #
+    # @example
+    #   ENV["APP_CONTACT"] = "api@example.com"
+    #   Variables.app_contact  # => "api@example.com"
     def self.app_contact
       ENV["APP_CONTACT"] || "Contact not stated"
     end

data/lib/api_adaptor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApiAdaptor
-  VERSION = "0.1.0"
+  VERSION = "1.0.1"
 end

data/lib/api_adaptor.rb

@@ -3,7 +3,37 @@
 require_relative "api_adaptor/version"
 require_relative "api_adaptor/base"
 
+# ApiAdaptor provides a framework for building JSON API clients with minimal boilerplate.
+#
+# It handles common patterns like request/response parsing, authentication, redirect handling,
+# pagination, and error management, allowing you to focus on your API's specific logic.
+#
+# @example Building a simple API client
+#   class MyApiClient < ApiAdaptor::Base
+#     def initialize
+#       super("https://api.example.com")
+#     end
+#
+#     def get_user(id)
+#       get_json("/users/#{id}")
+#     end
+#
+#     def create_user(data)
+#       post_json("/users", data)
+#     end
+#   end
+#
+#   client = MyApiClient.new
+#   user = client.get_user(123)
+#
+# @example Using JSONClient directly
+#   client = ApiAdaptor::JSONClient.new(bearer_token: "abc123")
+#   response = client.get_json("https://api.example.com/data")
+#   puts response["items"]
+#
+# @see Base Base class for building API clients
+# @see JSONClient Low-level HTTP client with JSON support
 module ApiAdaptor
+  # Base error class for all ApiAdaptor exceptions
   class Error < StandardError; end
-  # Your code goes here...
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: api_adaptor
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Huw Diprose
@@ -119,6 +119,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -147,6 +161,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -189,6 +217,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: A basic adaptor to send HTTP requests and parse the responses. Intended
   to bootstrap the quick writing of Adaptors for specific APIs, without having to
   write the same old JSON request and processing time and time again.
@@ -201,7 +243,9 @@ files:
 - ".env.example"
 - ".rspec"
 - ".rubocop.yml"
+- ".yardopts"
 - CHANGELOG.md
+- CLAUDE.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -242,7 +286,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.6
 specification_version: 4
 summary: A basic adaptor to send HTTP requests and parse the responses.
 test_files: []