poodle-ruby 1.0.0

data/lib/poodle/errors/validation_error.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative "base_error"
+
+module Poodle
+  # Exception raised when request validation fails (400 Bad Request, 422 Unprocessable Entity)
+  #
+  # @example Handling validation errors
+  #   begin
+  #     client.send_email(invalid_email)
+  #   rescue Poodle::ValidationError => e
+  #     puts "Validation failed: #{e.message}"
+  #     e.errors.each do |field, messages|
+  #       puts "#{field}: #{messages.join(', ')}"
+  #     end
+  #   end
+  class ValidationError < Error
+    # @return [Hash] field-specific validation errors
+    attr_reader :errors
+
+    # Initialize a new ValidationError
+    #
+    # @param message [String] the error message
+    # @param errors [Hash] field-specific validation errors
+    # @param context [Hash] additional context information
+    # @param status_code [Integer] HTTP status code (400 or 422)
+    def initialize(message = "Validation failed", errors: {}, context: {}, status_code: 400)
+      @errors = errors
+      super(message, context: context.merge(errors: errors), status_code: status_code)
+    end
+
+    # Create a ValidationError for invalid email address
+    #
+    # @param email [String] the invalid email address
+    # @param field [String] the field name (default: "email")
+    # @return [ValidationError] the validation error
+    def self.invalid_email(email, field: "email")
+      new(
+        "Invalid email address provided",
+        errors: { field => ["'#{email}' is not a valid email address"] }
+      )
+    end
+
+    # Create a ValidationError for missing required field
+    #
+    # @param field [String] the missing field name
+    # @return [ValidationError] the validation error
+    def self.missing_field(field)
+      new(
+        "Missing required field: #{field}",
+        errors: { field => ["The #{field} field is required"] }
+      )
+    end
+
+    # Create a ValidationError for invalid content
+    #
+    # @return [ValidationError] the validation error
+    def self.invalid_content
+      new(
+        "Email must contain either HTML content, text content, or both",
+        errors: { content: ["At least one content type (html or text) is required"] }
+      )
+    end
+
+    # Create a ValidationError for content too large
+    #
+    # @param field [String] the field name
+    # @param max_size [Integer] the maximum allowed size
+    # @return [ValidationError] the validation error
+    def self.content_too_large(field, max_size)
+      new(
+        "Content size exceeds maximum allowed size of #{max_size} bytes",
+        errors: { field => ["Content size exceeds maximum allowed size of #{max_size} bytes"] }
+      )
+    end
+
+    # Create a ValidationError for invalid field value
+    #
+    # @param field [String] the field name
+    # @param value [String] the invalid value
+    # @param reason [String] the reason why it's invalid
+    # @return [ValidationError] the validation error
+    def self.invalid_field_value(field, value, reason = "")
+      message = "Invalid value for field '#{field}': #{value}"
+      message += ". #{reason}" unless reason.empty?
+
+      new(
+        message,
+        errors: { field => [message] }
+      )
+    end
+  end
+end

data/lib/poodle/http_client.rb

@@ -0,0 +1,327 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "configuration"
+require_relative "errors/authentication_error"
+require_relative "errors/payment_error"
+require_relative "errors/forbidden_error"
+require_relative "errors/rate_limit_error"
+require_relative "errors/validation_error"
+require_relative "errors/network_error"
+require_relative "errors/server_error"
+
+module Poodle
+  # HTTP client wrapper for Poodle API communication
+  #
+  # @example Basic usage
+  #   config = Poodle::Configuration.new(api_key: "your_api_key")
+  #   client = Poodle::HttpClient.new(config)
+  #   response = client.post("api/v1/send-email", email_data)
+  class HttpClient
+    # @return [Configuration] the configuration object
+    attr_reader :config
+
+    # Initialize a new HttpClient
+    #
+    # @param config [Configuration] the configuration object
+    def initialize(config)
+      @config = config
+      @connection = build_connection
+    end
+
+    # Send a POST request
+    #
+    # @param endpoint [String] the API endpoint
+    # @param data [Hash] the request data
+    # @param headers [Hash] additional headers
+    # @return [Hash] the parsed response data
+    # @raise [Poodle::Error] if the request fails
+    def post(endpoint, data = {}, headers = {})
+      request(:post, endpoint, data, headers)
+    end
+
+    # Send a GET request
+    #
+    # @param endpoint [String] the API endpoint
+    # @param params [Hash] query parameters
+    # @param headers [Hash] additional headers
+    # @return [Hash] the parsed response data
+    # @raise [Poodle::Error] if the request fails
+    def get(endpoint, params = {}, headers = {})
+      request(:get, endpoint, params, headers)
+    end
+
+    private
+
+    # Send an HTTP request
+    #
+    # @param method [Symbol] the HTTP method
+    # @param endpoint [String] the API endpoint
+    # @param data [Hash] the request data or query parameters
+    # @param headers [Hash] additional headers
+    # @return [Hash] the parsed response data
+    # @raise [Poodle::Error] if the request fails
+    def request(method, endpoint, data = {}, headers = {})
+      url = @config.url_for(endpoint)
+
+      log_request(method, url, data) if @config.debug?
+
+      response = perform_request(method, url, data, headers)
+
+      log_response(response) if @config.debug?
+
+      handle_response(response)
+    rescue Faraday::TimeoutError => e
+      puts "TimeoutError: #{e.message}"
+      raise NetworkError.connection_timeout(@config.timeout)
+    rescue Faraday::ConnectionFailed => e
+      handle_connection_failed_error(e)
+    rescue Faraday::Error => e
+      raise NetworkError.connection_failed(@config.base_url, original_error: e)
+    end
+
+    # Perform the actual HTTP request
+    #
+    # @param method [Symbol] the HTTP method
+    # @param url [String] the request URL
+    # @param data [Hash] the request data
+    # @param headers [Hash] additional headers
+    # @return [Faraday::Response] the HTTP response
+    def perform_request(method, url, data, headers)
+      case method
+      when :post
+        @connection.post(url) do |req|
+          req.headers.update(headers)
+          req.body = data.to_json
+        end
+      when :get
+        @connection.get(url) do |req|
+          req.headers.update(headers)
+          req.params = data
+        end
+      else
+        raise ArgumentError, "Unsupported HTTP method: #{method}"
+      end
+    end
+
+    # Handle connection failed errors
+    #
+    # @param error [Faraday::ConnectionFailed] the connection error
+    # @raise [NetworkError] the appropriate network error
+    def handle_connection_failed_error(error)
+      if error.message.include?("SSL") || error.message.include?("certificate")
+        raise NetworkError.ssl_error(error.message)
+      elsif error.message.include?("resolve") || error.message.include?("DNS")
+        host = URI.parse(@config.base_url).host
+        raise NetworkError.dns_resolution_failed(host)
+      else
+        raise NetworkError.connection_failed(@config.base_url, original_error: error)
+      end
+    end
+
+    # Build the Faraday connection
+    #
+    # @return [Faraday::Connection] the configured connection
+    def build_connection
+      Faraday.new do |conn|
+        configure_connection_middleware(conn)
+        configure_connection_timeouts(conn)
+        configure_connection_headers(conn)
+        configure_custom_options(conn)
+      end
+    end
+
+    # Configure connection middleware
+    #
+    # @param conn [Faraday::Connection] the connection
+    def configure_connection_middleware(conn)
+      conn.request :json
+      conn.response :json, content_type: /\bjson$/
+      conn.adapter Faraday.default_adapter
+    end
+
+    # Configure connection timeouts
+    #
+    # @param conn [Faraday::Connection] the connection
+    def configure_connection_timeouts(conn)
+      conn.options.timeout = @config.timeout
+      conn.options.open_timeout = @config.connect_timeout
+    end
+
+    # Configure connection headers
+    #
+    # @param conn [Faraday::Connection] the connection
+    def configure_connection_headers(conn)
+      conn.headers["Authorization"] = "Bearer #{@config.api_key}"
+      conn.headers["Content-Type"] = "application/json"
+      conn.headers["Accept"] = "application/json"
+      conn.headers["User-Agent"] = @config.user_agent
+    end
+
+    # Configure custom HTTP options
+    #
+    # @param conn [Faraday::Connection] the connection
+    def configure_custom_options(conn)
+      @config.http_options.each do |key, value|
+        conn.options[key] = value
+      end
+    end
+
+    # Handle HTTP response
+    #
+    # @param response [Faraday::Response] the HTTP response
+    # @return [Hash] the parsed response data
+    # @raise [Poodle::Error] if the response indicates an error
+    def handle_response(response)
+      return response.body || {} if success_response?(response)
+
+      handle_error_response(response)
+    end
+
+    # Check if response is successful
+    #
+    # @param response [Faraday::Response] the HTTP response
+    # @return [Boolean] true if successful
+    def success_response?(response)
+      (200..299).cover?(response.status)
+    end
+
+    # Handle error responses
+    #
+    # @param response [Faraday::Response] the HTTP response
+    # @raise [Poodle::Error] the appropriate error
+    def handle_error_response(response)
+      case response.status
+      when 400
+        handle_validation_error(response)
+      when 401
+        raise AuthenticationError.invalid_api_key
+      when 402
+        handle_payment_error(response)
+      when 403
+        handle_forbidden_error(response)
+      when 422
+        handle_validation_error(response, status_code: 422)
+      when 429
+        raise RateLimitError.from_headers(response.headers)
+      when 500..599
+        handle_server_error(response)
+      else
+        raise NetworkError.http_error(response.status, extract_error_message(response))
+      end
+    end
+
+    # Handle validation errors (400, 422)
+    #
+    # @param response [Faraday::Response] the HTTP response
+    # @param status_code [Integer] the HTTP status code
+    # @raise [ValidationError] the validation error
+    def handle_validation_error(response, status_code: 400)
+      body = response.body || {}
+      message = extract_error_message(response)
+      errors = extract_validation_errors(body)
+
+      raise ValidationError.new(message, errors: errors, status_code: status_code)
+    end
+
+    # Handle payment errors (402)
+    #
+    # @param response [Faraday::Response] the HTTP response
+    # @raise [PaymentError] the payment error
+    def handle_payment_error(response)
+      message = extract_error_message(response)
+
+      case message
+      when /subscription.*expired/i
+        raise PaymentError.subscription_expired
+      when /trial.*limit/i
+        raise PaymentError.trial_limit_reached
+      when /monthly.*limit/i
+        raise PaymentError.monthly_limit_reached
+      else
+        raise PaymentError, message
+      end
+    end
+
+    # Handle forbidden errors (403)
+    #
+    # @param response [Faraday::Response] the HTTP response
+    # @raise [ForbiddenError] the forbidden error
+    def handle_forbidden_error(response)
+      body = response.body || {}
+      message = extract_error_message(response)
+
+      raise ForbiddenError.insufficient_permissions unless message.include?("suspended")
+
+      # Extract suspension details if available
+      reason = body["reason"] || "unknown"
+      rate = body["rate"]
+      raise ForbiddenError.account_suspended(reason, rate)
+    end
+
+    # Handle server errors (5xx)
+    #
+    # @param response [Faraday::Response] the HTTP response
+    # @raise [ServerError] the server error
+    def handle_server_error(response)
+      message = extract_error_message(response)
+
+      case response.status
+      when 500
+        raise ServerError.internal_server_error(message)
+      when 502
+        raise ServerError.bad_gateway(message)
+      when 503
+        raise ServerError.service_unavailable(message)
+      when 504
+        raise ServerError.gateway_timeout(message)
+      else
+        raise ServerError.new(message, status_code: response.status)
+      end
+    end
+
+    # Extract error message from response
+    #
+    # @param response [Faraday::Response] the HTTP response
+    # @return [String] the error message
+    def extract_error_message(response)
+      body = response.body
+      return "HTTP #{response.status} error" unless body.is_a?(Hash)
+
+      body["message"] || body["error"] || "HTTP #{response.status} error"
+    end
+
+    # Extract validation errors from response body
+    #
+    # @param body [Hash] the response body
+    # @return [Hash] field-specific validation errors
+    def extract_validation_errors(body)
+      return {} unless body.is_a?(Hash)
+
+      errors = body["errors"] || body["validation_errors"] || {}
+      return {} unless errors.is_a?(Hash)
+
+      # Convert string values to arrays for consistency
+      errors.transform_values { |v| Array(v) }
+    end
+
+    # Log HTTP request for debugging
+    #
+    # @param method [Symbol] the HTTP method
+    # @param url [String] the request URL
+    # @param data [Hash] the request data
+    def log_request(method, url, data)
+      puts "[Poodle] #{method.upcase} #{url}"
+      puts "[Poodle] Request: #{data.to_json}" unless data.empty?
+    end
+
+    # Log HTTP response for debugging
+    #
+    # @param response [Faraday::Response] the HTTP response
+    def log_response(response)
+      puts "[Poodle] Response: #{response.status}"
+      puts "[Poodle] Body: #{response.body}" if response.body
+    end
+  end
+end

data/lib/poodle/rails/railtie.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Poodle
+  module Rails
+    # Rails Railtie for automatic Poodle integration
+    class Railtie < ::Rails::Railtie
+      # Add Poodle configuration to Rails generators
+      config.generators do |g|
+        g.test_framework :rspec
+      end
+
+      # Initialize Poodle after Rails application is initialized
+      initializer "poodle.configure" do |app|
+        # Auto-configure Poodle if credentials or environment variables are present
+        if ENV["POODLE_API_KEY"] ||
+           (app.credentials.respond_to?(:poodle_api_key) && app.credentials.poodle_api_key)
+          Poodle::Rails.auto_configure!
+        end
+      end
+
+      # Add Poodle logger integration
+      initializer "poodle.logger" do |_app|
+        # Integrate with Rails logger if debug mode is enabled
+        if Poodle::Rails.configured? && Poodle::Rails.configuration.debug?
+          # Override the HTTP client logging to use Rails logger
+          Poodle::HttpClient.class_eval do
+            private
+
+            def log_request(method, url, data)
+              ::Rails.logger.debug "[Poodle] #{method.upcase} #{url}"
+              ::Rails.logger.debug "[Poodle] Request: #{data.to_json}" unless data.empty?
+            end
+
+            def log_response(response)
+              ::Rails.logger.debug "[Poodle] Response: #{response.status}"
+              ::Rails.logger.debug "[Poodle] Body: #{response.body}" if response.body
+            end
+          end
+        end
+      end
+
+      # Add rake tasks
+      rake_tasks do
+        load "poodle/rails/tasks.rake"
+      end
+    end
+  end
+end

data/lib/poodle/rails/tasks.rake

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+namespace :poodle do
+  desc "Check Poodle configuration"
+  task config: :environment do
+    if Poodle::Rails.configured?
+      config = Poodle::Rails.configuration
+      puts "✅ Poodle is configured"
+      puts "   API Key: #{config.api_key ? "***#{config.api_key[-4..]}" : 'Not set'}"
+      puts "   Base URL: #{config.base_url}"
+      puts "   Timeout: #{config.timeout}s"
+      puts "   Debug: #{config.debug?}"
+    else
+      puts "❌ Poodle is not configured"
+      puts "   Set POODLE_API_KEY environment variable or configure in Rails credentials"
+    end
+  end
+
+  desc "Test Poodle connection"
+  task test: :environment do
+    unless Poodle::Rails.configured?
+      puts "❌ Poodle is not configured. Run 'rake poodle:config' to check configuration."
+      exit 1
+    end
+
+    begin
+      client = Poodle::Rails.client
+      puts "✅ Poodle client created successfully"
+      puts "   SDK Version: #{Poodle::VERSION}"
+      puts "   User Agent: #{client.config.user_agent}"
+    rescue StandardError => e
+      puts "❌ Failed to create Poodle client: #{e.message}"
+      exit 1
+    end
+  end
+
+  desc "Send a test email"
+  task :send_test, %i[to from] => :environment do |_t, args|
+    unless Poodle::Rails.configured?
+      puts "❌ Poodle is not configured. Run 'rake poodle:config' to check configuration."
+      exit 1
+    end
+
+    to_email = args[:to] || ENV.fetch("POODLE_TEST_TO", nil)
+    from_email = args[:from] || ENV["POODLE_TEST_FROM"] || "test@example.com"
+
+    unless to_email
+      puts "❌ Please provide a recipient email address:"
+      puts "   rake poodle:send_test[recipient@example.com]"
+      puts "   or set POODLE_TEST_TO environment variable"
+      exit 1
+    end
+
+    begin
+      client = Poodle::Rails.client
+      response = client.send(
+        from: from_email,
+        to: to_email,
+        subject: "Test Email from Poodle Ruby SDK",
+        html: "<h1>Test Email</h1><p>This is a test email sent from the Poodle Ruby SDK in a Rails application.</p>",
+        text: "Test Email\n\nThis is a test email sent from the Poodle Ruby SDK in a Rails application."
+      )
+
+      if response.success?
+        puts "✅ Test email sent successfully!"
+        puts "   From: #{from_email}"
+        puts "   To: #{to_email}"
+        puts "   Message: #{response.message}"
+      else
+        puts "❌ Failed to send test email: #{response.message}"
+        exit 1
+      end
+    rescue StandardError => e
+      puts "❌ Error sending test email: #{e.message}"
+      puts "   #{e.class.name}"
+      exit 1
+    end
+  end
+
+  desc "Generate Poodle initializer"
+  task install: :environment do
+    initializer_path = Rails.root.join("config", "initializers", "poodle.rb")
+
+    if File.exist?(initializer_path)
+      puts "⚠️  Poodle initializer already exists at #{initializer_path}"
+      puts "   Remove it first if you want to regenerate it."
+      exit 1
+    end
+
+    initializer_content = <<~RUBY
+      # frozen_string_literal: true
+
+      # Poodle email sending configuration
+      Poodle::Rails.configure do |config|
+        # API key from Rails credentials or environment variable
+        config.api_key = Rails.application.credentials.poodle_api_key || ENV['POODLE_API_KEY']
+
+        # Optional: Override base URL (defaults to https://api.usepoodle.com)
+        # config.base_url = ENV['POODLE_BASE_URL']
+
+        # Optional: Set timeout (defaults to 30 seconds)
+        # config.timeout = 30
+
+        # Optional: Enable debug mode in development
+        config.debug = Rails.env.development?
+      end
+    RUBY
+
+    File.write(initializer_path, initializer_content)
+    puts "✅ Created Poodle initializer at #{initializer_path}"
+    puts "   Don't forget to set your API key in Rails credentials or environment variables!"
+  end
+end