hookdeck 0.1.0

data/lib/hookdeck/configuration.rb

@@ -0,0 +1,31 @@
+module Hookdeck
+  class Configuration
+    DEFAULTS = {
+      api_base: 'https://api.hookdeck.com',
+      api_version: '2024-09-01'
+    }.freeze
+
+    attr_accessor :api_key, :api_base, :api_version
+
+    def initialize
+      DEFAULTS.each do |key, value|
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    # Validates the configuration.
+    #
+    # @raise [Hookdeck::ValidationError] If the API key is not provided.
+    def validate!
+      validate_api_version!
+    end
+
+    private
+
+    def validate_api_version!
+      return if api_version.match?(/^\d{4}-\d{2}-\d{2}$/)
+
+      raise ValidationError, "Invalid API version format. Expected YYYY-MM-DD, got #{api_version}"
+    end
+  end
+end

data/lib/hookdeck/errors.rb

@@ -0,0 +1,123 @@
+module Hookdeck
+  class Error < StandardError
+    attr_reader :message, :request_id
+
+    def initialize(message = nil, request_id = nil)
+      @message = message
+      @request_id = request_id
+      super(error_message)
+    end
+
+    private
+
+    def error_message
+      request_id ? "#{message} (Request ID: #{request_id})" : message
+    end
+  end
+
+  class ValidationError < Error; end
+
+  class ApiError < Error
+    attr_reader :response,
+                :handled,
+                :status,
+                :message,
+                :data,
+                :request_id
+
+    def initialize(response = nil)
+      @response = response
+      parse_error_response(response&.dig(:body))
+      @request_id = response&.dig(:headers, 'x-request-id')
+      super(message, request_id)
+    end
+
+    private
+
+    def parse_error_response(body)
+      error_data = parse_body(body)
+      @handled = error_data['handled']
+      @status = error_data['status']
+      @message = error_data['message']
+      @data = error_data['data']
+    end
+
+    def parse_body(body)
+      return {} unless body
+
+      body.is_a?(String) ? JSON.parse(body) : body
+    rescue JSON::ParserError
+      {
+        'handled' => true,
+        'status' => response&.dig(:status),
+        'message' => body.to_s,
+        'data' => {}
+      }
+    end
+  end
+
+  class BadRequestError < ApiError
+    def initialize(response)
+      super
+      @status = 400
+    end
+  end
+
+  class UnauthorizedError < ApiError
+    def initialize(response)
+      super
+      @status = 401
+    end
+  end
+
+  class ForbiddenError < ApiError
+    def initialize(response)
+      super
+      @status = 403
+    end
+  end
+
+  class NotFoundError < ApiError
+    def initialize(response)
+      super
+      @status = 404
+    end
+  end
+
+  class UnprocessableEntityError < ApiError
+    def initialize(response)
+      super
+      @status = 422
+    end
+  end
+
+  class RateLimitError < ApiError
+    attr_reader :retry_after
+
+    def initialize(response)
+      super
+      @status = 429
+      @retry_after = response&.dig(:headers, 'retry-after')&.to_i
+    end
+  end
+
+  class ServerError < ApiError
+    def initialize(response)
+      super
+      @status = response&.dig(:status) || 500
+    end
+  end
+
+  class ConnectionError < Error
+    attr_reader :original_error
+
+    def initialize(error)
+      @original_error = error
+      super(error.message)
+    end
+  end
+
+  class TimeoutError < ConnectionError; end
+
+  class SSLError < ConnectionError; end
+end

data/lib/hookdeck/http_client.rb

@@ -0,0 +1,39 @@
+class HttpClient
+  attr_reader :config
+
+  def initialize(config)
+    @config = config
+    @connection_pools = {}
+  end
+
+  def connection
+    Thread.current[:hookdeck_client] ||= build_connection
+  end
+
+  def build_connection
+    Faraday.new(url: config.api_base) do |faraday|
+      setup_request_middleware(faraday)
+      setup_response_middleware(faraday)
+      setup_error_handling(faraday)
+      faraday.adapter :net_http
+    end
+  end
+
+  def setup_request_middleware(faraday)
+    faraday.request :json
+    # faraday.request :retry, max: config.max_retries, interval: config.retry_interval
+    faraday.request :authorization, 'Bearer', config.api_key
+
+    # faraday.use Middleware::RequestId, prefix: config.request_id_prefix
+    # faraday.use Middleware::Logging, logger: config.logger
+  end
+
+  def setup_response_middleware(faraday)
+    faraday.response :json, content_type: /\bjson$/
+    # faraday.response :logger, config.logger, bodies: true if config.logger
+  end
+
+  def setup_error_handling(faraday)
+    # faraday.use Middleware::ErrorHandler
+  end
+end

data/lib/hookdeck/middlewares/error_handler.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module HookDeck
+  module Middleware
+    # ErrorHandler is a Faraday middleware that provides standardized error handling
+    # for HTTP requests. It catches Faraday errors and converts them into specific
+    # HookDeck error types based on the response status and error type
+    #
+    class ErrorHandler < Faraday::Middleware
+      # Executes the middleware
+      # @param env [Hash] The Faraday environment hash
+      # @raise [HookDeck::Error] Various error types based on the response
+      def call(env)
+        @app.call(env)
+      rescue Faraday::Error => e
+        handle_error(e, env)
+      end
+
+      private
+
+      # Maps Faraday errors to HookDeck-specific errors
+      # @param error [Faraday::Error] The original Faraday error
+      # @param _env [Hash] The Faraday environment hash
+      # @raise [HookDeck::Error] Converted error type
+      def handle_error(error, _env)
+        case error
+        when Faraday::ClientError
+          handle_client_error(error.response)
+        when Faraday::ServerError
+          handle_server_error(error.response)
+        when Faraday::ConnectionFailed
+          raise ConnectionError, error
+        when Faraday::TimeoutError
+          raise TimeoutError, error
+        when Faraday::SSLError
+          raise SSLError, error
+        else
+          raise Error, error.message
+        end
+      end
+
+      # Maps HTTP status codes to specific client errors
+      # @param response [Hash] The error response hash
+      # @raise [HookDeck::Error] Specific client error type
+      def handle_client_error(response)
+        error_class = case response[:status]
+                      when 400 then BadRequestError
+                      when 401 then UnauthorizedError
+                      when 403 then ForbiddenError
+                      when 404 then NotFoundError
+                      when 409 then ConflictError
+                      when 422 then UnprocessableEntityError
+                      when 429 then RateLimitError
+                      else ApiError
+                      end
+
+        raise error_class, response
+      end
+
+      # Handles server-side errors
+      # @param response [Hash] The error response hash
+      # @raise [HookDeck::ServerError] Server error
+      def handle_server_error(response)
+        raise ServerError, response
+      end
+    end
+  end
+end

data/lib/hookdeck/middlewares/logging.rb

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+module HookDeck
+  module Middleware
+    # Logging middleware that provides detailed request/response logging with security-aware filtering.
+    # Automatically redacts sensitive information from headers and request/response bodies.
+    #
+    class Logging < Faraday::Middleware
+      # Initialize the logging middleware
+      # @param app [#call] The Faraday app
+      # @param logger [Logger, nil] Optional custom logger (defaults to STDOUT logger)
+      def initialize(app, logger: nil)
+        super(app)
+        @logger = logger || default_logger
+      end
+
+      # Executes the middleware, logging request and response details
+      # @param env [Hash] The Faraday environment hash
+      def call(env)
+        start_time = Time.now
+        log_request(env)
+
+        @app.call(env).on_complete do |response_env|
+          duration = Time.now - start_time
+          log_response(response_env, duration)
+        end
+      rescue StandardError => e
+        log_error(e)
+        raise
+      end
+
+      private
+
+      # Logs request details with sensitive data filtered
+      def log_request(env)
+        @logger.info do
+          {
+            method: env.method.upcase,
+            url: env.url.to_s,
+            body: sanitize_body(env.body),
+            headers: sanitize_headers(env.request_headers),
+            request_id: env.request_headers['X-Request-Id']
+          }.to_json
+        end
+      end
+
+      # Logs response details with timing information
+      def log_response(env, duration)
+        @logger.info do
+          {
+            method: env.method.upcase,
+            url: env.url.to_s,
+            status: env.status,
+            duration: duration.round(3),
+            headers: sanitize_headers(env.response_headers),
+            request_id: env.request_headers['X-Request-Id']
+          }.to_json
+        end
+      end
+
+      # Logs error details with backtrace
+      # @param error [StandardError] The caught error
+      def log_error(error)
+        @logger.error do
+          {
+            error: error.class.name,
+            message: error.message,
+            backtrace: error.backtrace&.first(5)
+          }.to_json
+        end
+      end
+
+      # Sanitizes request/response body by filtering sensitive data
+      # @param body [String, nil] The raw body
+      # @return [Hash, String, nil] Sanitized body
+      def sanitize_body(body)
+        return nil if body.nil?
+        return body unless body.is_a?(String)
+
+        begin
+          parsed = JSON.parse(body)
+          sanitize_hash(parsed)
+        rescue JSON::ParserError
+          'Unparseable body'
+        end
+      end
+
+      # Recursively sanitizes hash values
+      # @param hash [Hash] Hash to sanitize
+      # @return [Hash] Sanitized hash
+      def sanitize_hash(hash)
+        hash.each_with_object({}) do |(key, value), sanitized|
+          sanitized[key] = if sensitive_key?(key)
+                             '[FILTERED]'
+                           elsif value.is_a?(Hash)
+                             sanitize_hash(value)
+                           elsif value.is_a?(Array)
+                             value.map { |v| v.is_a?(Hash) ? sanitize_hash(v) : v }
+                           else
+                             value
+                           end
+        end
+      end
+
+      # Sanitizes headers by filtering sensitive values
+      # @param headers [Hash] Headers to sanitize
+      # @return [Hash] Sanitized headers
+      def sanitize_headers(headers)
+        headers.each_with_object({}) do |(key, value), sanitized|
+          sanitized[key] = if sensitive_header?(key)
+                             '[FILTERED]'
+                           else
+                             value
+                           end
+        end
+      end
+
+      # Checks if a key contains sensitive information
+      # @param key [String, Symbol] Key to check
+      # @return [Boolean] true if sensitive
+      def sensitive_key?(key)
+        key.to_s.downcase.match?(/password|token|key|secret|credential|auth/)
+      end
+
+      # Checks if a header contains sensitive information
+      # @param header [String, Symbol] Header to check
+      # @return [Boolean] true if sensitive
+      def sensitive_header?(header)
+        header.to_s.downcase.match?(/authorization|x-api-key|cookie/)
+      end
+
+      # Creates a default logger if none provided
+      # @return [Logger] Configured logger
+      def default_logger
+        logger = Logger.new($stdout)
+        logger.progname = 'hookdeck'
+        logger.formatter = proc do |severity, datetime, progname, msg|
+          "#{datetime} [#{progname}] #{severity}: #{msg}\n"
+        end
+        logger
+      end
+    end
+  end
+end

data/lib/hookdeck/middlewares/request_id.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module HookDeck
+  module Middleware
+    # Middleware that automatically generates and manages request IDs for HTTP requests.
+    # Adds both server and client request IDs to facilitate request tracking and debugging.
+    #
+    class RequestId < Faraday::Middleware
+      # Initialize the request ID middleware
+      # @param app [#call] The Faraday app
+      # @param options [Hash] Configuration options
+      # @option options [String] :prefix ('req') Prefix for generated request IDs
+      def initialize(app, options = {})
+        super(app)
+        @prefix = options.fetch(:prefix, 'req')
+      end
+
+      # Executes the middleware, adding and tracking request IDs
+      def call(env)
+        env.request_headers['X-Request-Id'] ||= generate_request_id
+        env.request_headers['X-Client-Request-Id'] ||= generate_request_id
+
+        @app.call(env).on_complete do |response_env|
+          # Store request IDs for potential error handling
+          response_env[:hookdeck_request_id] = response_env.response_headers['x-request-id']
+          response_env[:hookdeck_client_request_id] = env.request_headers['X-Client-Request-Id']
+        end
+      end
+
+      private
+
+      # Generates a unique request ID with configured prefix
+      # @return [String] Request ID in format "prefix_hexstring"
+      def generate_request_id
+        "#{@prefix}_#{SecureRandom.hex(16)}"
+      end
+    end
+  end
+end

data/lib/hookdeck/resources/attempt.rb

@@ -0,0 +1,24 @@
+module Hookdeck
+  module Resources
+    # @example List recent attempts
+    #   client.attempts.list(limit: 10)
+    #
+    # @example Retrieve specific attempt
+    #   attempt = client.attempts.retrieve('atm_123')
+    #
+    class Attempt < Base
+      def list(params = {})
+        get('attempts', params)
+      end
+
+      # Retrieves an attempt by ID.
+      #
+      # @param id [String] The ID of the attempt.
+      # @return [Hash] The attempt.
+      def retrieve(id)
+        validate_id!(id, 'atm_')
+        get("attempts/#{id}")
+      end
+    end
+  end
+end

data/lib/hookdeck/resources/base.rb

@@ -0,0 +1,174 @@
+module Hookdeck
+  module Resources
+    class Base
+      attr_reader :client
+
+      def initialize(client)
+        @client = client
+      end
+
+      protected
+
+      def get(path, params = {})
+        request(:get, path, params)
+      end
+
+      def post(path, params = {})
+        request(:post, path, params)
+      end
+
+      def put(path, params = {})
+        request(:put, path, params)
+      end
+
+      def delete(path, params = {})
+        request(:delete, path, params)
+      end
+
+      private
+
+      def request(method, path, params = {}, opts = {})
+        path = ensure_api_version(path)
+        handle_response(
+          client.request(
+            method,
+            path,
+            params,
+            opts
+          )
+        )
+      end
+
+      def ensure_api_version(path)
+        "/#{client.config.api_version}/#{path.gsub(%r{^/}, '')}"
+      end
+
+      def handle_response(response)
+        return nil if response.nil?
+
+        response
+      rescue StandardError => e
+        handle_error(e)
+      end
+
+      def handle_error(error)
+        case error
+        when Faraday::ClientError
+          case error.response[:status]
+          when 400
+            raise BadRequestError, error.response
+          when 401
+            raise UnauthorizedError, error.response
+          when 403
+            raise ForbiddenError, error.response
+          when 404
+            raise NotFoundError, error.response
+          when 409
+            raise ConflictError, error.response
+          when 422
+            raise UnprocessableEntityError, error.response
+          when 429
+            raise RateLimitError, error.response
+          else
+            raise ApiError, error.response
+          end
+        when Faraday::ServerError
+          raise ServerError, error.response
+        when Faraday::ConnectionFailed
+          raise ConnectionError, error
+        when Faraday::TimeoutError
+          raise TimeoutError, error
+        when Faraday::SSLError
+          raise SSLError, error
+        else
+          raise Error, error.message
+        end
+      end
+
+      def validate_id!(id, prefix)
+        return if id.is_a?(String) && id.start_with?(prefix)
+
+        raise ValidationError, "Invalid ID format. Expected #{prefix}*, got: #{id}"
+      end
+
+      def validate_params!(params, required_keys = [], optional_keys = [])
+        # Check for required keys
+        missing_keys = required_keys - params.keys
+        raise ValidationError, "Missing required parameters: #{missing_keys.join(', ')}" if missing_keys.any?
+
+        # Check for unexpected keys
+        allowed_keys = required_keys + optional_keys
+        unexpected_keys = params.keys - allowed_keys
+        return unless unexpected_keys.any?
+
+        raise ValidationError, "Unexpected parameters: #{unexpected_keys.join(', ')}"
+      end
+
+      def validate_enum!(value, allowed_values, field_name)
+        return if allowed_values.include?(value)
+
+        raise ValidationError, "Invalid #{field_name}. Expected one of: #{allowed_values.join(', ')}, got: #{value}"
+      end
+
+      def validate_array!(value, field_name, allowed_values = nil)
+        raise ValidationError, "#{field_name} must be an array, got: #{value.class}" unless value.is_a?(Array)
+
+        return unless allowed_values && (invalid_values = value - allowed_values).any?
+
+        raise ValidationError, "Invalid #{field_name} values: #{invalid_values.join(', ')}"
+      end
+
+      def validate_timestamp!(value, field_name)
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        raise ValidationError, "Invalid timestamp format for #{field_name}: #{value}"
+      end
+
+      def validate_boolean!(value, field_name)
+        return if [true, false].include?(value)
+
+        raise ValidationError, "#{field_name} must be a boolean, got: #{value}"
+      end
+
+      def validate_integer!(value, field_name, min: nil, max: nil)
+        raise ValidationError, "#{field_name} must be an integer, got: #{value.class}" unless value.is_a?(Integer)
+
+        raise ValidationError, "#{field_name} must be greater than or equal to #{min}" if min && value < min
+
+        return unless max && value > max
+
+        raise ValidationError, "#{field_name} must be less than or equal to #{max}"
+      end
+
+      def validate_string!(value, field_name, pattern: nil, min_length: nil, max_length: nil)
+        raise ValidationError, "#{field_name} must be a string, got: #{value.class}" unless value.is_a?(String)
+
+        raise ValidationError, "#{field_name} format is invalid" if pattern && !value.match?(pattern)
+
+        if min_length && value.length < min_length
+          raise ValidationError, "#{field_name} must be at least #{min_length} characters"
+        end
+
+        return unless max_length && value.length > max_length
+
+        raise ValidationError, "#{field_name} must be at most #{max_length} characters"
+      end
+
+      def validate_url!(value, field_name)
+        uri = URI.parse(value)
+        unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+          raise ValidationError,
+                "Invalid URL format for #{field_name}"
+        end
+      rescue URI::InvalidURIError
+        raise ValidationError, "Invalid URL format for #{field_name}"
+      end
+
+      def format_timestamp(value)
+        return nil if value.nil?
+
+        value.is_a?(Time) ? value.iso8601 : value
+      end
+    end
+  end
+end