hybiscus_pdf_report 0.1.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a8661a6c187761886b7a0e41f3112957a31eff162cc42c3167bfeb2be793dcc4
-  data.tar.gz: 36465eed4413bcaa80b5d05893cd24cdeea139c1d1795b7526dd03c9d11b6de4
+  metadata.gz: 0007a7c6d4494de9ca87ab92f259b192ad550d26172d225f5be109823a514298
+  data.tar.gz: ccc6a69f6c7d28b34b168a240b059c9e54c51a0802097ff829bb07111909ea53
 SHA512:
-  metadata.gz: '0463680072442b123263ea823606daae30a64489babe71db6078731645a42d12847df20f390d16ddc09becc8400b48490d009ccf2208e5faaf9c108e52de7a64'
-  data.tar.gz: 690d63a2dd4e4414fc20e526b260c284560d393a33d5c6038f1f708812bddb24ac823c07710a315abc714b9049b7a09d07c2b57bb688cdd4c63b1eedc70fed97
+  metadata.gz: efbe50eb7882ce18576a146b77593e19364176b819973ded959f57d1f6a279982789839fb2503e34f66ca2022ff2bff5148d5c3c76d7f8ccb249cc68df756a4e
+  data.tar.gz: 63c0076efef641022cbf9be95a074bb0903b9386308ab7eb1541b6d2a456854c55831e4e17ab08171cf56fe41e4c33f4aa59605ff36edd937c2437cf5363f879

data/.rubocop.yml

@@ -12,4 +12,5 @@ Style/StringLiteralsInInterpolation:
 Layout/LineLength:
   Max: 120
 
-
+Metrics/BlockLength:
+  AllowedMethods: ['describe', 'context']

data/README.md

@@ -1,6 +1,6 @@
-# Hybiscus API Ruby Wrapper
+# Hybiscus PDF Report Ruby Gem
 
-This is the API Wrapper for the Hybiscus REST API
+A Ruby client library for the [Hybiscus PDF Reports API](https://hybiscus.dev/), providing an easy way to generate PDF reports from JSON data.
 
 ## Installation
 
@@ -12,74 +12,289 @@ gem 'hybiscus_pdf_report'
 
 And then execute:
 
-    $ bundle install
+```bash
+bundle install
+```
 
 Or install it yourself as:
 
-    $ gem install hybiscus_pdf_report
+```bash
+gem install hybiscus_pdf_report
+```
+
+## Configuration
+
+### Environment Variables (Recommended)
+
+Set your API key and optionally the API URL as environment variables:
+
+```bash
+export HYBISCUS_API_KEY="your_api_key_here"
+export HYBISCUS_API_URL="https://api.hybiscus.dev/api/v1/"  # Optional, defaults to this URL
+```
+
+### Programmatic Configuration
+
+You can also configure the gem programmatically:
+
+```ruby
+HybiscusPdfReport.configure do |config|
+  config.api_key = "your_api_key_here"
+  config.api_url = "https://api.hybiscus.dev/api/v1/"  # Optional
+  config.timeout = 30  # Optional, defaults to 10 seconds
+end
+```
 
 ## Usage
-### Configure the client
-The Gem is configured by default to work with the public platform of Hybiscus at
-* API: `https://api.hybiscus.dev/api/v1/`
 
-### Instantiate a client
+### Creating a Client
+
 ```ruby
-# To connect to the default SaaS Instance of Adnexo: https://prod.api.ax-track.ch/api/v1
-client = HybiscusPdfReport::Client.new(api_key: your_api_key)
-# Or if you have set ENV['HIBISCUS_API_KEY'] set, you don't need to pass in the api key.
+# Using environment variables (recommended)
 client = HybiscusPdfReport::Client.new
 
-# The default time out is 10 seconds. To change the value, pass in the parameter
-client = HybiscusPdfReport::Client.new(api_key: your_api_key, timeout: 20)
+# Or passing the API key directly
+client = HybiscusPdfReport::Client.new(api_key: "your_api_key_here")
 
-# If you have a Hybiscus in your private cloud and have a different URL, you can pass the URL as a parameter
-client = HybiscusPdfReport::Client.new(hibiskus_api_url: #URL#)
-# You can also set the URL as  ENV["HIBISCUS_API_URL"]
-```
+# With custom timeout
+client = HybiscusPdfReport::Client.new(
+  api_key: "your_api_key_here",
+  timeout: 30
+)
 
-## Accessing the Endpoints
-### Submit to 'build-report'
-```ruby
-response = client.request.build_report(json)
+# With custom API URL (for private cloud instances)
+client = HybiscusPdfReport::Client.new(
+  api_key: "your_api_key_here",
+  api_url: "https://your-private-hybiscus-instance.com/api/v1/"
+)
 ```
-The Response object is returned, containint the `task_id` AND the task `status`. These information are also stored and can be accessed as follows
+
+### API Endpoints
+
+#### 1. Build Report
+
+Submit a report request for processing:
+
 ```ruby
-response = client.request.last_task_id
-response = client.request.last_task_status
+# Your report JSON data
+report_data = { _JSON_structure }
+
+response = client.request.build_report(report_data)
+
+# Access response data
+puts response.task_id
+puts response.status
 ```
 
-### Submit to 'preview-report'
+#### 2. Preview Report
+
+Generate a preview of your report without consuming your quota:
+
 ```ruby
-response = client.request.preview_report(json)
+response = client.request.preview_report(report_data)
+puts response.task_id
+puts response.status
 ```
-### Submit to 'get-task-status'
+
+#### 3. Check Task Status
+
+Monitor the status of a report generation task:
+
 ```ruby
-response = client.request.get_task_status(task_id)
-# if you previously already made a request, you can get the status of the last task directly without having to store and pass the task_id
+# Using a specific task ID
+response = client.request.get_task_status("task_id_here")
+
+# Or check the status of the last submitted task
 response = client.request.get_last_task_status
+puts response.status  # "pending", "processing", "completed", "failed"
 ```
 
-### Submit to 'get-report'
+#### 4. Download Report
+
+Retrieve the generated PDF report:
+
 ```ruby
-response = client.request.get_report(task_id)
-# if you previously already made a request, you can get the status of the last task directly without having to store and pass the task_id
+# Using a specific task ID
+response = client.request.get_report("task_id_here")
+
+# Or get the last generated report
 response = client.request.get_last_report
+
+# The report is base64 encoded
+pdf_content = Base64.decode64(response.report)
+
+# Save to file
+File.open("report.pdf", "wb") do |file|
+  file.write(pdf_content)
+end
+```
+
+#### 5. Check Remaining Quota
+
+Check your remaining API quota:
+
+```ruby
+response = client.request.get_remaining_quota
+puts response.remaining_single_page_reports
+puts response.remaining_multi_page_reports
+```
+
+### Complete Workflow Example
+
+```ruby
+require 'hybiscus_pdf_report'
+require 'base64'
+
+# Initialize client
+client = HybiscusPdfReport::Client.new
+
+# Prepare report data
+report_data = { _SOME_JSON_STRUCTURE_ }
+
+begin
+  # Submit report for processing
+  response = client.request.build_report(report_data)
+  task_id = response.task_id
+
+  puts "Report submitted. Task ID: #{task_id}"
+
+  # Poll for completion
+  loop do
+    status_response = client.request.get_task_status(task_id)
+    status = status_response.status
+
+    puts "Current status: #{status}"
+
+    case status
+    when "completed"
+      puts "Report generation completed!"
+      break
+    when "failed"
+      puts "Report generation failed!"
+      exit 1
+    when "pending", "processing"
+      puts "Still processing... waiting 5 seconds"
+      sleep 5
+    end
+  end
+
+  # Download the completed report
+  report_response = client.request.get_report(task_id)
+  pdf_content = Base64.decode64(report_response.report)
+
+  # Save to file
+  File.open("generated_report.pdf", "wb") do |file|
+    file.write(pdf_content)
+  end
+
+  puts "Report saved as generated_report.pdf"
+
+rescue HybiscusPdfReport::ApiErrors::ApiRequestsQuotaReachedError => e
+  puts "API quota reached: #{e.message}"
+rescue HybiscusPdfReport::ApiErrors::PaymentRequiredError => e
+  puts "Payment required: #{e.message}"
+rescue HybiscusPdfReport::ApiErrors::RateLimitError => e
+  puts "Rate limit error persisted after automatic retries: #{e.message}"
+rescue HybiscusPdfReport::ApiErrors::ApiError => e
+  puts "API error: #{e.message}"
+rescue ArgumentError => e
+  puts "Argument error: #{e.message}"
+end
+```
+
+### Error Handling
+
+The gem includes specific error classes for different API error conditions and **automatically handles transient errors** like rate limits and network timeouts with exponential backoff retry logic.
+
+#### Automatic Retry Handling
+
+The gem automatically retries the following errors up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s):
+
+- `RateLimitError` (HTTP 503) - When the API is temporarily overloaded
+- `Faraday::TimeoutError` - Network timeout errors
+- `Faraday::ConnectionFailed` - Network connection failures
+
+You don't need to handle these errors manually - the gem will automatically retry and only raise an exception if all retry attempts are exhausted.
+
+#### Manual Error Handling
+
+For other API errors, you should handle them explicitly in your code:
+
+```ruby
+begin
+  response = client.request.build_report(report_data)
+rescue HybiscusPdfReport::ApiErrors::ApiRequestsQuotaReachedError => e
+  puts "API quota reached (HTTP 429). Please upgrade your plan."
+rescue HybiscusPdfReport::ApiErrors::PaymentRequiredError => e
+  puts "Payment required (HTTP 402). Please check your account."
+rescue HybiscusPdfReport::ApiErrors::UnauthorizedError => e
+  puts "Unauthorized (HTTP 401). Please check your API key."
+rescue HybiscusPdfReport::ApiErrors::BadRequestError => e
+  puts "Bad request (HTTP 400). Please check your request data."
+rescue HybiscusPdfReport::ApiErrors::RateLimitError => e
+  puts "Rate limit error persisted after retries. Please try again later."
+rescue HybiscusPdfReport::ApiErrors::ApiError => e
+  puts "API error: #{e.message} (HTTP #{e.status_code})"
+end
+```
+
+#### Available Error Classes
+
+- `BadRequestError` (HTTP 400) - Invalid request data
+- `UnauthorizedError` (HTTP 401) - Invalid or missing API key
+- `PaymentRequiredError` (HTTP 402) - Payment required for the account
+- `ForbiddenError` (HTTP 403) - Access forbidden
+- `NotFoundError` (HTTP 404) - Resource not found
+- `UnprocessableContentError` (HTTP 422) - Request data cannot be processed
+- `ApiRequestsQuotaReachedError` (HTTP 429) - API request quota exceeded
+- `RateLimitError` (HTTP 503) - Rate limit exceeded (automatically retried)
+
+### Response Objects
+
+All API responses return `Response` objects that provide dynamic attribute access:
+
+```ruby
+response = client.request.build_report(report_data)
+
+# Access attributes dynamically
+puts response.task_id
+puts response.status
+
+# Response objects support nested attribute access
+if response.respond_to?(:error)
+  puts response.error.message
+end
 ```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Console Testing
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+```bash
+bin/console
+```
+
+Then in the console:
 
-To test the application in the console
 ```ruby
-client = HybiscusPdfReport::Client.new(api_key: _YOUR_API_KEY_)
-# to get a list of all trackers (just as an example)
-client.trackers.all
+client = HybiscusPdfReport::Client.new(api_key: "your_api_key")
+response = client.request.get_remaining_quota
+puts response.remaining_single_page_reports
 ```
 
+## Requirements
+
+- Ruby >= 3.0.0
+- Faraday HTTP client library
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/Timly-Software-AG/HybiscusPdfReportRubyGem.
@@ -88,7 +303,10 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/Timly-
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-## Open development
-* Pagination for development
+## Links
+
+- [Hybiscus PDF Reports API Documentation](https://hybiscus.dev/)
+- [GitHub Repository](https://github.com/Timly-Software-AG/HybiscusPdfReportRubyGem)
+- [RubyGems.org](https://rubygems.org/gems/hybiscus_pdf_report)
 
 

data/hybiscus_pdf_report.gemspec

@@ -23,7 +23,8 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) ||
-        f.start_with?(*%w[bin/ test/ spec/ features/ .git .gitlab-ci.yml appveyor Gemfile])
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .gitlab-ci.yml appveyor Gemfile]) ||
+        f.end_with?(".gem")
     end
   end
   spec.bindir = "exe"

data/lib/hybiscus_pdf_report/api_errors.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# These errors are automatically raised by the client based on HTTP status codes returned
+# by the Hybiscus API. Extend or rescue these as needed in application code.
+
+module HybiscusPdfReport
+  # rubocop:disable Style/CommentedKeyword
+  # Base error class for all Hybiscus PDF Report API errors.
+  class ApiError < StandardError
+    attr_reader :response, :status_code
+
+    def initialize(message = nil, response: nil, status_code: nil)
+      super(message)
+      @response = response
+      @status_code = status_code
+    end
+  end
+
+  class BadRequestError              < ApiError; end # 400
+  class UnauthorizedError            < ApiError; end # 401
+  class PaymentRequiredError         < ApiError; end # 402
+  class ForbiddenError               < ApiError; end # 403
+  class NotFoundError                < ApiError; end # 404
+  class UnprocessableContentError    < ApiError; end # 422
+  class ApiRequestsQuotaReachedError < ApiError; end # 429
+  class RateLimitError               < ApiError; end # 503
+  # rubocop:enable Style/CommentedKeyword
+
+  HTTP_ERROR_STATUS_CODES = {
+    400 => BadRequestError,
+    401 => UnauthorizedError,
+    402 => PaymentRequiredError,
+    403 => ForbiddenError,
+    404 => NotFoundError,
+    422 => UnprocessableContentError,
+    429 => ApiRequestsQuotaReachedError,
+    503 => RateLimitError
+  }.freeze
+
+  HTTP_OK_CODE = 200
+end

data/lib/hybiscus_pdf_report/client.rb

@@ -1,32 +1,50 @@
 # frozen_string_literal: true
 
 require "faraday"
-require_relative "errors"
+require_relative "api_errors"
+require_relative "config"
 
 module HybiscusPdfReport
-  # Client handling the Faraday connection to the Hybiscus PDF Reports API
+  # HTTP client for the Hybiscus PDF Reports API.
+  #
+  # This class handles all HTTP communication with the Hybiscus API, including
+  # authentication, connection management, and request routing. It uses Faraday
+  # for HTTP requests and supports custom adapters for testing.
+  #
+  # @example Basic usage
+  #   client = HybiscusPdfReport::Client.new(api_key: "your_api_key")
+  #   response = client.request.build_report(report_data)
+  #
+  # @example Using environment variables
+  #   ENV["HYBISCUS_API_KEY"] = "your_api_key"
+  #   client = HybiscusPdfReport::Client.new
+  #
+  # @example Custom configuration
+  #   client = HybiscusPdfReport::Client.new(
+  #     api_key: "your_key",
+  #     api_url: "https://api.hybiscus.dev/api/v1/",
+  #     timeout: 30
+  #   )
   class Client
-    attr_reader :api_key, :hibiskus_api_url, :adapter, :last_request, :email
-
-    BASE_URL_API = "https://api.hybiscus.dev/api/v1/"
-
-    def initialize(api_key: ENV["HIBISCUS_API_KEY"],
-                   hibiskus_api_url: ENV["HIBISCUS_API_URL"],
-                   timeout: nil,
-                   adapter: nil,
-                   stubs: nil)
-      @api_key            = api_key&.strip
-      # default to the main Adnexo production account
-      raise ArgumentError, "No API key defined. Check documentation on how to set the API key." if @api_key.nil?
-
-      @hibiskus_api_url   = hibiskus_api_url || BASE_URL_API
-      # default to the main Adnexo production account
-      @timeout            = timeout
+    attr_reader :api_key, :api_url, :adapter, :last_request
+
+    # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def initialize(api_key: nil, api_url: nil, timeout: nil, adapter: nil, stubs: nil)
+      @api_key = (api_key || config.api_key)&.strip
+      if @api_key.nil? || @api_key.empty?
+        raise ArgumentError,
+              "No API key defined. Set it in config or pass to Client.new."
+      end
+
+      @api_url = api_url || config.api_url
+      @timeout = timeout || config.timeout
+
       # param made available for testing purposes: In the rspec tests the following adapter is used: :test
       # https://www.rubydoc.info/gems/faraday/Faraday/Adapter/Test
-      @adapter            = adapter || Faraday.default_adapter
-      @stubs              = stubs
+      @adapter = adapter || config.adapter
+      @stubs   = stubs || config.stubs
     end
+    # rubocop:enable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
     def request
       @request ||= Request.new(self)
@@ -41,16 +59,21 @@ module HybiscusPdfReport
     # rubocop:disable Metrics/AbcSize
     def build_connection(header)
       Faraday.new do |conn|
-        conn.url_prefix = hibiskus_api_url ## typically the base URL
+        conn.url_prefix = api_url ## typically the base URL
         conn.request :json
         conn.response :json, content_type: "application/json"
         conn.adapter adapter, @stubs
-        conn.headers["X-API-KEY"] = api_key.to_s unless api_key.empty?
+        conn.headers["X-API-KEY"] = api_key unless api_key.nil? || api_key.empty?
         # adds additional header information to the connection
+
         header.each { |key, value| conn.headers[key] = value }
         conn.options.timeout = @timeout || 10
       end
     end
     # rubocop:enable Metrics/AbcSize
+
+    def config
+      @config ||= HybiscusPdfReport.config
+    end
   end
 end

data/lib/hybiscus_pdf_report/config.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+# Main module for the Hybiscus PDF Report gem
+module HybiscusPdfReport
+  # Configuration class for the Hybiscus PDF Report gem.
+  #
+  # This class manages all configuration settings including API credentials,
+  # URLs, timeouts, and connection adapters. Configuration can be set through
+  # environment variables or programmatically.
+  #
+  # @example Setting configuration programmatically
+  #   HybiscusPdfReport.configure do |config|
+  #     config.api_key = "your_api_key"
+  #     config.api_url = "https://api.hybiscus.dev/api/v1/"
+  #     config.timeout = 30
+  #   end
+  #
+  # @example Using environment variables
+  #   ENV["HYBISCUS_API_KEY"] = "your_api_key"
+  #   ENV["HYBISCUS_API_URL"] = "https://api.hybiscus.dev/api/v1/"
+  class Config
+    attr_accessor :api_key, :api_url, :timeout, :adapter, :stubs
+
+    DEFAULT_API_URL = "https://api.hybiscus.dev/api/v1/"
+    DEFAULT_TIMEOUT = 10
+
+    def initialize
+      @api_key = ENV["HYBISCUS_API_KEY"]
+      @api_url = ENV["HYBISCUS_API_URL"] || DEFAULT_API_URL
+      @timeout = DEFAULT_TIMEOUT
+      @adapter = Faraday.default_adapter
+      @stubs   = nil
+    end
+  end
+
+  # yields the global configuration
+  def self.configure
+    yield(config)
+  end
+
+  # returns the global config instance
+  def self.config
+    @config ||= Config.new
+  end
+end

data/lib/hybiscus_pdf_report/errors.rb

@@ -1,25 +1,38 @@
 # frozen_string_literal: true
 
-# Definition of all errors that can be raised by the Hybiscus PDF Reports API
+# These errors are automatically raised by the client based on HTTP status codes returned
+# by the Hybiscus API. Extend or rescue these as needed in application code.
+
 module HybiscusPdfReport
-  ApiError = Class.new(StandardError)
-  BadRequestError = Class.new(ApiError)
-  UnauthorizedError = Class.new(ApiError)
-  PaymentRequiredError = Class.new(ApiError)
-  ForbiddenError = Class.new(ApiError)
-  ApiRequestsQuotaReachedError = Class.new(ApiError)
-  NotFoundError = Class.new(ApiError)
-  UnprocessableEntityError = Class.new(ApiError)
-  RateLimitError = Class.new(ApiError)
+  class ApiError < StandardError; end
+
+  # 400
+  class BadRequestError              < ApiError; end
+  # 401
+  class UnauthorizedError            < ApiError; end
+  # 402
+  class PaymentRequiredError         < ApiError; end
+  # 403
+  class ForbiddenError               < ApiError; end
+  # 404
+  class NotFoundError                < ApiError; end
+  # 422
+  class UnprocessableContentError    < ApiError; end
+  # 429
+  class ApiRequestsQuotaReachedError < ApiError; end
+  # 503
+  class RateLimitError               < ApiError; end
 
-  HTTP_OK_CODE                    = 200
+  HTTP_ERROR_STATUS_CODES = {
+    400 => BadRequestError,
+    401 => UnauthorizedError,
+    402 => PaymentRequiredError,
+    403 => ForbiddenError,
+    404 => NotFoundError,
+    422 => UnprocessableContentError,
+    429 => ApiRequestsQuotaReachedError,
+    503 => RateLimitError
+  }.freeze
 
-  HTTP_BAD_REQUEST_CODE           = 400
-  HTTP_UNAUTHORIZED_CODE          = 401
-  HTTP_PAYMENT_REQUIRED_CODE      = 402
-  HTTP_FORBIDDEN_CODE             = 403
-  HTTP_NOT_FOUND_CODE             = 404
-  HTTP_UNPROCESSABLE_CONTENT_CODE = 422
-  HTTP_UNPROCESSABLE_ENTITY_CODE  = 429
-  HTTP_SERVICE_UNAVAILABLE_CODE   = 503
+  HTTP_OK_CODE = 200
 end

data/lib/hybiscus_pdf_report/object.rb

@@ -1,25 +1,12 @@
 # frozen_string_literal: true
 
-require "ostruct"
-
+# Legacy placeholder file for backward compatibility
+# This file exists for historical reasons and may be removed in future versions.
+# Use HybiscusPdfReport::ResponseObject instead.
 module HybiscusPdfReport
-  # Base class for all objects returned by the Hybiscus PDF Reports API
-  class Object
-    def initialize(attributes)
-      @attributes = OpenStruct.new(attributes)
-    end
-
-    def method_missing(method, *args, &block)
-      attribute = @attributes.send(method, *args, &block)
-
-      return super if attribute.nil?
-      return Object.new(attribute) if attribute.is_a?(Hash)
-
-      attribute
-    end
-
-    def respond_to_missing?(method, _include_private = false)
-      @attributes.respond_to? method
-    end
+  # Placeholder for legacy compatibility
+  # @deprecated Use ResponseObject instead
+  module Object
+    # This module is deprecated
   end
 end

data/lib/hybiscus_pdf_report/objects/response.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
+# Response wrapper class for Hybiscus PDF Report API responses
+require_relative "../response_object"
+
 module HybiscusPdfReport
-  class Response < Object
+  # Standard response object that inherits from ResponseObject
+  class Response < HybiscusPdfReport::ResponseObject
   end
 end

data/lib/hybiscus_pdf_report/report_builder.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "erb"
+require "pathname"
+
+module HybiscusPdfReport
+  # Base class for building PDF reports with JSON templates
+  #
+  # This class allows users to create custom report builders by inheriting from it.
+  # It provides a simple way to generate JSON structures for the Hybiscus API using ERB templates.
+  #
+  # Usage:
+  #   class InvoiceReport < HybiscusPdfReport::ReportBuilder
+  #     def initialize(invoice:, **options)
+  #       @invoice = invoice
+  #       super(report_name: "Invoice Report", **options)
+  #     end
+  #   end
+  #
+  #   report = InvoiceReport.new(invoice: my_invoice)
+  #   json_data = report.generate
+  class ReportBuilder
+    DEFAULT_TEMPLATE_DIR = File.dirname(__FILE__)
+
+    attr_reader :report_name, :template_dir
+
+    def initialize(report_name: nil, template_dir: nil, **template_params)
+      # Set the report name - use provided name or derive from class name
+      @report_name = report_name || derive_report_name
+      @template_dir = template_dir || DEFAULT_TEMPLATE_DIR
+
+      # Dynamically set all parameters as instance variables
+      template_params.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    # Main method to generate the report JSON
+    # Returns a JSON string that can be sent to the Hybiscus API
+    def generate
+      render_json
+    end
+
+    # Returns the full path to the template file
+    def template_path
+      File.join(template_dir, template_name)
+    end
+
+    # Returns the template filename (can be overridden in subclasses)
+    def template_name
+      "#{underscore(class_name)}.json.erb"
+    end
+
+    def load_configuration_first?
+      # By default, we assume the report doesn't require pre-loading configuration.
+      # This can be overridden in subclasses if configuration loading is needed.
+      false
+    end
+
+    private
+
+    # Renders the ERB template with all instance variables available
+    def render_json
+      unless File.exist?(template_path)
+        raise "Template file not found: #{template_path}. " \
+              "Create a template file or override the render_json method."
+      end
+
+      template_content = File.read(template_path)
+      template = ERB.new(template_content)
+
+      # Render the template with all instance variables in scope
+      template.result(binding)
+    end
+
+    # Derives a report name from the class name
+    def derive_report_name
+      humanize(class_name)
+    end
+
+    # Returns the class name without module prefix
+    def class_name
+      self.class.name.split("::").last
+    end
+
+    # Converts CamelCase to snake_case
+    def underscore(string)
+      string
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .downcase
+    end
+
+    # Converts CamelCase to human readable format
+    def humanize(string)
+      underscore(string).tr("_", " ").split.map(&:capitalize).join(" ")
+    end
+  end
+end

data/lib/hybiscus_pdf_report/request.rb

@@ -2,12 +2,12 @@
 
 require "json"
 require "base64"
+require "pry"
 
 module HybiscusPdfReport
   # Request Handler with the individual endpoints handling the communication with the Hybiscus PDF Reports API
   class Request
-    attr_reader :client, :response, :last_request_time_counting_against_rate_limit, :last_task_id, :last_task_status,
-                :remaining_single_page_reports, :remaining_multi_page_reports
+    attr_reader :client, :response, :last_request_time_counting_against_rate_limit, :last_task_id, :last_task_status
 
     def initialize(client)
       @client = client
@@ -20,21 +20,15 @@ module HybiscusPdfReport
     def build_report(report_request_as_json)
       response_body = request(endpoint: "build-report", http_method: :post, body: report_request_as_json)
       ## HANDLE 402 RESPONSE --> PAYMENT REQUIRED
-      update_last_request_information
+      update_last_request_information(response_body)
 
-      response = Response.new(response_body.merge(
-                                remaining_single_page_reports: @response.headers["x-remaining-single-page-reports"],
-                                remaining_multi_page_reports: @response.headers["x-remaining-multi-page-reports"]
-                              ))
-
-      update_quota_information(response)
-      response
+      @response = Response.new(response_body)
     end
 
     # POST
     def preview_report(report_request_as_json)
       response_body = request(endpoint: "preview-report", http_method: :post, body: report_request_as_json)
-      update_last_request_information
+      update_last_request_information(response_body)
       Response.new(response_body)
     end
 
@@ -43,7 +37,7 @@ module HybiscusPdfReport
       response_body = request(endpoint: "get-task-status", params: { task_id: task_id })
       # The last task status is stored. If this method is called with the same task_id, the last task status is updated
       # in the instance variable
-      @last_task_status = response.body["status"] if last_task_id == task_id
+      @last_task_status = response_body["status"] if last_task_id == task_id
       Response.new(response_body)
     end
 
@@ -55,7 +49,7 @@ module HybiscusPdfReport
 
     def get_report(task_id)
       response_body = request(endpoint: "get-report", http_method: :get, params: { task_id: task_id })
-      Response.new(satus: response.status, content: Base64.encode64(response_body))
+      Response.new(report: Base64.encode64(response_body), status: HTTP_OK_CODE)
     end
 
     def get_last_report
@@ -76,60 +70,43 @@ module HybiscusPdfReport
     def request(endpoint:, http_method: :get, headers: {}, params: {}, body: {})
       raise "Client not defined" unless defined? @client
 
-      @response = client.connection.public_send(http_method, endpoint, params.merge(body), headers)
-      raise_error unless response_successful? && no_json_error?
+      retry_wrapper = RequestRetryWrapper.new(logger: defined?(Rails) ? Rails.logger : nil)
+
+      response_body = retry_wrapper.with_retries do
+        @response = client.connection.public_send(http_method, endpoint, params.merge(body), headers)
+        raise_error unless response_successful? && no_json_error?
+
+        # Return raw body for binary data (no JSON parsing)
+        @response.body
+      end
 
       @last_request = Time.now
 
-      response.body
+      response_body
     end
 
-    def update_last_request_information
+    def update_last_request_information(response_body)
       @last_request_time_counting_against_rate_limit = Time.now
-      @last_task_id = response.body["task_id"]
-      @last_task_status = response.body["status"]
-    end
-
-    def update_quota_information(response_object)
-      @remaining_single_page_reports = response_object.remaining_single_page_reports
-      @remaining_multi_page_reports = response_object.remaining_multi_page_reports
+      @last_task_id = response_body["task_id"]
+      @last_task_status = response_body["status"]
     end
 
     def raise_error
-      pretty_print_json_response
+      # logger.debug response.body
 
       raise error_class(response.status), "Code: #{response.status}, response: #{response.reason_phrase}"
     end
 
-    # rubocop: disable Metrics/Metrics/MethodLength
     def error_class(status)
-      case status
-      when HTTP_BAD_REQUEST_CODE
-        BadRequestError
-      when HTTP_UNAUTHORIZED_CODE
-        UnauthorizedError
-      when HTTP_NOT_FOUND_CODE, HTTP_FORBIDDEN_CODE
-        NotFoundError
-      when HTTP_UNPROCESSABLE_ENTITY_CODE
-        UnprocessableEntityError
-      when HTTP_PAYMENT_REQUIRED_CODE
-        PaymentRequiredError
-      when HTTP_SERVICE_UNAVAILABLE_CODE
-        # Hybiscus API returns 503 when the rate limit is reached
-        # https://hybiscus.dev/docs/api/rate-limitting
-        RateLimitError
-      else
-        ApiError
-      end
+      HybiscusPdfReport::HTTP_ERROR_STATUS_CODES[status] || ApiError
     end
-    # rubocop: enable Metrics/Metrics/MethodLength
 
     def response_successful?
       response.status == HTTP_OK_CODE
     end
 
     def no_json_error?
-      response.status != HTTP_UNPROCESSABLE_CONTENT_CODE
+      response.status != HybiscusPdfReport::UnprocessableContentError
     end
 
     def pretty_print_json_response

data/lib/hybiscus_pdf_report/request_retry_wrapper.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "faraday"
+require_relative "api_errors"
+
+module HybiscusPdfReport
+  # RequestRetryWrapper provides automatic retry logic for transient errors
+  # when communicating with the Hybiscus API (e.g., rate limits, timeouts).
+  #
+  # Usage:
+  #   wrapper = HybiscusPdfReport::RequestRetryWrapper.new(max_attempts: 3)
+  #   wrapper.with_retries do
+  #     api_client.perform_request
+  #   end
+  #
+  # Retries will apply exponential backoff (1s, 2s, 4s, etc.)
+  # and will log retry attempts if a logger is provided.
+  class RequestRetryWrapper
+    DEFAULT_RETRY_ERRORS = [
+      RateLimitError,
+      Faraday::TimeoutError,
+      Faraday::ConnectionFailed
+    ].freeze
+
+    def initialize(max_attempts: 5, base_delay: 1, logger: nil)
+      @max_attempts = max_attempts
+      @base_delay = base_delay
+      @logger = logger
+    end
+
+    def with_retries
+      attempts = 0
+
+      begin
+        yield
+      rescue *DEFAULT_RETRY_ERRORS => e
+        attempts += 1
+        handle_retry_or_raise(e, attempts)
+        retry
+      end
+    end
+
+    private
+
+    def handle_retry_or_raise(error, attempts)
+      if attempts >= @max_attempts
+        log_retry_exhausted(error, attempts)
+        raise error
+      else
+        wait_time = compute_delay(attempts)
+        log_retry_attempt(error, attempts, wait_time)
+        sleep(wait_time)
+      end
+    end
+
+    def compute_delay(attempts)
+      @base_delay * (2**(attempts - 1))
+    end
+
+    def log_retry_attempt(error, attempts, wait_time)
+      log("Retry ##{attempts} in #{wait_time}s due to #{error.class}: #{error.message}")
+    end
+
+    def log_retry_exhausted(error, attempts)
+      log("Retries exhausted after #{attempts} attempts: #{error.class} - #{error.message}")
+    end
+
+    def log(message)
+      @logger&.warn(message) || puts("[HybiscusRetry] #{message}")
+    end
+  end
+end

data/lib/hybiscus_pdf_report/response_object.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "ostruct"
+
+module HybiscusPdfReport
+  # Base class for all objects returned by the Hybiscus PDF Reports API
+  class ResponseObject
+    def initialize(attributes)
+      @original_attributes = attributes || {}
+      @attributes = OpenStruct.new(@original_attributes)
+    end
+
+    # Delegate certain OpenStruct methods directly
+    def to_h
+      @attributes.to_h
+    end
+
+    def to_s
+      @attributes.to_s
+    end
+
+    def inspect
+      @attributes.inspect
+    end
+
+    def method_missing(method, *args, &block)
+      # Handle attribute access
+      if @attributes.respond_to?(method)
+        attribute = @attributes.send(method, *args, &block)
+        return attribute.is_a?(Hash) ? ResponseObject.new(attribute) : attribute
+      end
+
+      # Try to access as OpenStruct attribute (this will return nil for non-existent attributes)
+      begin
+        attribute = @attributes.public_send(method, *args, &block)
+        attribute.is_a?(Hash) ? ResponseObject.new(attribute) : attribute
+      rescue NoMethodError
+        # If OpenStruct doesn't recognize it, delegate to super
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      @attributes.respond_to?(method) || super
+    end
+  end
+end

data/lib/hybiscus_pdf_report/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+# Version information for the Hybiscus PDF Report gem
 module HybiscusPdfReport
-  VERSION = "0.1.0"
+  VERSION = "0.9.1"
 end

data/lib/hybiscus_pdf_report.rb

@@ -4,8 +4,30 @@ require_relative "hybiscus_pdf_report/version"
 
 # Service to interact with the Hybiscus PDF Reports API
 module HybiscusPdfReport
+  # Core functionality
   autoload :Client, "hybiscus_pdf_report/client"
-  autoload :Request, "hybiscus_pdf_report/request"
-  autoload :Object, "hybiscus_pdf_report/object"
+  autoload :Config, "hybiscus_pdf_report/config"
   autoload :Response, "hybiscus_pdf_report/objects/response"
+
+  # Request handling and retries
+  autoload :Request, "hybiscus_pdf_report/request"
+  autoload :RequestRetryWrapper, "hybiscus_pdf_report/request_retry_wrapper"
+
+  # Object handling
+  autoload :ResponseObject, "hybiscus_pdf_report/response_object"
+
+  # Error handling
+  autoload :APIErrors, "hybiscus_pdf_report/api_errors"
+
+  # Report building
+  autoload :ReportBuilder, "hybiscus_pdf_report/report_builder"
+
+  # Module-level configuration
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.configure
+    yield(config) if block_given?
+  end
 end

data/sig/hybiscus_pdf_report.rbs

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hybiscus_pdf_report
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Philipp Baumann
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-12-10 00:00:00.000000000 Z
+date: 2025-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -68,11 +68,16 @@ files:
 - Rakefile
 - hybiscus_pdf_report.gemspec
 - lib/hybiscus_pdf_report.rb
+- lib/hybiscus_pdf_report/api_errors.rb
 - lib/hybiscus_pdf_report/client.rb
+- lib/hybiscus_pdf_report/config.rb
 - lib/hybiscus_pdf_report/errors.rb
 - lib/hybiscus_pdf_report/object.rb
 - lib/hybiscus_pdf_report/objects/response.rb
+- lib/hybiscus_pdf_report/report_builder.rb
 - lib/hybiscus_pdf_report/request.rb
+- lib/hybiscus_pdf_report/request_retry_wrapper.rb
+- lib/hybiscus_pdf_report/response_object.rb
 - lib/hybiscus_pdf_report/version.rb
 - sig/hybiscus_pdf_report.rbs
 homepage: https://hybiscus.dev/