poodle-ruby 1.0.0

data/examples/basic_usage.rb

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "poodle"
+
+# Basic usage example for the Poodle Ruby SDK
+
+# Set your API key (you can also use environment variables)
+# ENV["POODLE_API_KEY"] = "your_api_key_here"
+
+begin
+  # Initialize the client
+  client = Poodle::Client.new(api_key: "your_api_key_here")
+
+  # Send a simple HTML email
+  response = client.send(
+    from: "sender@example.com",
+    to: "recipient@example.com",
+    subject: "Hello from Poodle Ruby SDK!",
+    html: "<h1>Hello World!</h1><p>This email was sent using the Poodle Ruby SDK.</p>"
+  )
+
+  if response.success?
+    puts "✅ Email sent successfully!"
+  else
+    puts "❌ Failed to send email"
+  end
+  puts "Message: #{response.message}"
+
+  # Send a text-only email
+  text_response = client.send_text(
+    from: "sender@example.com",
+    to: "recipient@example.com",
+    subject: "Plain text email",
+    text: "This is a plain text email sent using the Poodle Ruby SDK."
+  )
+
+  puts "\nText email result: #{text_response.success? ? 'Success' : 'Failed'}"
+
+  # Send an HTML-only email
+  html_response = client.send_html(
+    from: "sender@example.com",
+    to: "recipient@example.com",
+    subject: "HTML email",
+    html: "<h2>Newsletter</h2><p>This is an HTML email with <strong>formatting</strong>.</p>"
+  )
+
+  puts "HTML email result: #{html_response.success? ? 'Success' : 'Failed'}"
+rescue Poodle::ValidationError => e
+  puts "❌ Validation error: #{e.message}"
+  puts "Errors: #{e.errors}"
+rescue Poodle::AuthenticationError => e
+  puts "❌ Authentication error: #{e.message}"
+  puts "Please check your API key"
+rescue Poodle::RateLimitError => e
+  puts "❌ Rate limit exceeded: #{e.message}"
+  puts "Retry after: #{e.retry_after} seconds" if e.retry_after
+rescue Poodle::Error => e
+  puts "❌ Poodle error: #{e.message}"
+  puts "Status code: #{e.status_code}" if e.status_code
+rescue StandardError => e
+  puts "❌ Unexpected error: #{e.message}"
+end

data/lib/poodle/client.rb

@@ -0,0 +1,222 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "http_client"
+require_relative "email"
+require_relative "email_response"
+require_relative "errors/validation_error"
+
+module Poodle
+  # Main Poodle SDK client for sending emails
+  #
+  # @example Basic usage
+  #   client = Poodle::Client.new(api_key: "your_api_key")
+  #   response = client.send(
+  #     from: "sender@example.com",
+  #     to: "recipient@example.com",
+  #     subject: "Hello World",
+  #     html: "<h1>Hello!</h1>"
+  #   )
+  #
+  # @example Using configuration object
+  #   config = Poodle::Configuration.new(
+  #     api_key: "your_api_key",
+  #     debug: true
+  #   )
+  #   client = Poodle::Client.new(config)
+  #
+  # @example Using environment variables
+  #   ENV["POODLE_API_KEY"] = "your_api_key"
+  #   client = Poodle::Client.new
+  class Client
+    # @return [Configuration] the configuration object
+    attr_reader :config
+
+    # @return [HttpClient] the HTTP client
+    attr_reader :http_client
+
+    # Initialize a new Client
+    #
+    # @param config_or_api_key [Configuration, String, nil] configuration object or API key
+    # @param base_url [String, nil] base URL (only used if first param is API key)
+    # @param timeout [Integer, nil] request timeout (only used if first param is API key)
+    # @param connect_timeout [Integer, nil] connection timeout (only used if first param is API key)
+    # @param debug [Boolean] enable debug mode (only used if first param is API key)
+    # @param http_options [Hash] additional HTTP options (only used if first param is API key)
+    #
+    # @example With API key
+    #   client = Poodle::Client.new("your_api_key")
+    #
+    # @example With configuration
+    #   config = Poodle::Configuration.new(api_key: "your_api_key")
+    #   client = Poodle::Client.new(config)
+    #
+    # @example With keyword arguments
+    #   client = Poodle::Client.new(
+    #     api_key: "your_api_key",
+    #     debug: true,
+    #     timeout: 60
+    #   )
+    def initialize(config_or_api_key = nil, **options)
+      @config = case config_or_api_key
+                when Configuration
+                  config_or_api_key
+                when String
+                  Configuration.new(
+                    api_key: config_or_api_key,
+                    base_url: options[:base_url],
+                    timeout: options[:timeout],
+                    connect_timeout: options[:connect_timeout],
+                    debug: options.fetch(:debug, false),
+                    http_options: options.fetch(:http_options, {})
+                  )
+                when nil
+                  # Support keyword arguments for convenience
+                  Configuration.new(**options)
+                else
+                  raise ArgumentError, "Expected Configuration object, API key string, or nil"
+                end
+
+      @http_client = HttpClient.new(@config)
+    end
+
+    # Send an email using an Email object or hash
+    #
+    # @param email [Email, Hash] the email to send
+    # @return [EmailResponse] the response from the API
+    # @raise [ValidationError] if email data is invalid
+    # @raise [Poodle::Error] if the request fails
+    #
+    # @example With Email object
+    #   email = Poodle::Email.new(
+    #     from: "sender@example.com",
+    #     to: "recipient@example.com",
+    #     subject: "Hello",
+    #     html: "<h1>Hello!</h1>"
+    #   )
+    #   response = client.send_email(email)
+    #
+    # @example With hash
+    #   response = client.send_email({
+    #     from: "sender@example.com",
+    #     to: "recipient@example.com",
+    #     subject: "Hello",
+    #     text: "Hello!"
+    #   })
+    def send_email(email)
+      email_obj = email.is_a?(Email) ? email : create_email_from_hash(email)
+
+      response_data = @http_client.post("v1/send-email", email_obj.to_h)
+      EmailResponse.from_api_response(response_data)
+    end
+
+    # Send an email with individual parameters
+    #
+    # @param from [String] sender email address
+    # @param to [String] recipient email address
+    # @param subject [String] email subject
+    # @param html [String, nil] HTML content
+    # @param text [String, nil] plain text content
+    # @return [EmailResponse] the response from the API
+    # @raise [ValidationError] if email data is invalid
+    # @raise [Poodle::Error] if the request fails
+    #
+    # @example
+    #   response = client.send(
+    #     from: "sender@example.com",
+    #     to: "recipient@example.com",
+    #     subject: "Hello World",
+    #     html: "<h1>Hello!</h1>",
+    #     text: "Hello!"
+    #   )
+    def send(from:, to:, subject:, html: nil, text: nil)
+      email = Email.new(from: from, to: to, subject: subject, html: html, text: text)
+      send_email(email)
+    end
+
+    # Send an HTML email
+    #
+    # @param from [String] sender email address
+    # @param to [String] recipient email address
+    # @param subject [String] email subject
+    # @param html [String] HTML content
+    # @return [EmailResponse] the response from the API
+    # @raise [ValidationError] if email data is invalid
+    # @raise [Poodle::Error] if the request fails
+    #
+    # @example
+    #   response = client.send_html(
+    #     from: "sender@example.com",
+    #     to: "recipient@example.com",
+    #     subject: "Newsletter",
+    #     html: "<h1>Newsletter</h1><p>Content here</p>"
+    #   )
+    def send_html(from:, to:, subject:, html:)
+      send(from: from, to: to, subject: subject, html: html)
+    end
+
+    # Send a plain text email
+    #
+    # @param from [String] sender email address
+    # @param to [String] recipient email address
+    # @param subject [String] email subject
+    # @param text [String] plain text content
+    # @return [EmailResponse] the response from the API
+    # @raise [ValidationError] if email data is invalid
+    # @raise [Poodle::Error] if the request fails
+    #
+    # @example
+    #   response = client.send_text(
+    #     from: "sender@example.com",
+    #     to: "recipient@example.com",
+    #     subject: "Simple notification",
+    #     text: "This is a simple text notification."
+    #   )
+    def send_text(from:, to:, subject:, text:)
+      send(from: from, to: to, subject: subject, text: text)
+    end
+
+    # Get the SDK version
+    #
+    # @return [String] the SDK version
+    def version
+      @config.class::SDK_VERSION
+    end
+
+    private
+
+    # Create an Email object from hash data
+    #
+    # @param data [Hash] email data
+    # @return [Email] the email object
+    # @raise [ValidationError] if required fields are missing
+    def create_email_from_hash(data)
+      validate_required_email_fields(data)
+      extract_email_from_hash(data)
+    end
+
+    # Validate required email fields
+    #
+    # @param data [Hash] email data
+    # @raise [ValidationError] if required fields are missing
+    def validate_required_email_fields(data)
+      raise ValidationError.missing_field("from") unless data[:from] || data["from"]
+      raise ValidationError.missing_field("to") unless data[:to] || data["to"]
+      raise ValidationError.missing_field("subject") unless data[:subject] || data["subject"]
+    end
+
+    # Extract email object from hash data
+    #
+    # @param data [Hash] email data
+    # @return [Email] the email object
+    def extract_email_from_hash(data)
+      Email.new(
+        from: data[:from] || data["from"],
+        to: data[:to] || data["to"],
+        subject: data[:subject] || data["subject"],
+        html: data[:html] || data["html"],
+        text: data[:text] || data["text"]
+      )
+    end
+  end
+end

data/lib/poodle/configuration.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Poodle
+  # Configuration class for Poodle SDK settings
+  #
+  # @example Basic configuration
+  #   config = Poodle::Configuration.new(api_key: "your_api_key")
+  #
+  # @example Using environment variables
+  #   ENV["POODLE_API_KEY"] = "your_api_key"
+  #   config = Poodle::Configuration.new
+  #
+  # @example Full configuration
+  #   config = Poodle::Configuration.new(
+  #     api_key: "your_api_key",
+  #     base_url: "https://api.usepoodle.com",
+  #     timeout: 30,
+  #     connect_timeout: 10,
+  #     debug: true
+  #   )
+  class Configuration
+    # Default API base URL
+    DEFAULT_BASE_URL = "https://api.usepoodle.com"
+
+    # Default timeout in seconds
+    DEFAULT_TIMEOUT = 30
+
+    # Default connect timeout in seconds
+    DEFAULT_CONNECT_TIMEOUT = 10
+
+    # Maximum content size in bytes (10MB)
+    MAX_CONTENT_SIZE = 10 * 1024 * 1024
+
+    # SDK version
+    SDK_VERSION = Poodle::VERSION
+
+    # @return [String] the API key for authentication
+    attr_reader :api_key
+
+    # @return [String] the base URL for the API
+    attr_reader :base_url
+
+    # @return [Integer] the request timeout in seconds
+    attr_reader :timeout
+
+    # @return [Integer] the connection timeout in seconds
+    attr_reader :connect_timeout
+
+    # @return [Boolean] whether debug mode is enabled
+    attr_reader :debug
+
+    # @return [Hash] additional HTTP client options
+    attr_reader :http_options
+
+    # Initialize a new Configuration
+    #
+    # @param api_key [String, nil] API key (defaults to POODLE_API_KEY env var)
+    # @param base_url [String, nil] Base URL (defaults to POODLE_BASE_URL env var or DEFAULT_BASE_URL)
+    # @param timeout [Integer, nil] Request timeout (defaults to POODLE_TIMEOUT env var or DEFAULT_TIMEOUT)
+    # @param connect_timeout [Integer, nil] Connect timeout (defaults to POODLE_CONNECT_TIMEOUT env var or
+    #   DEFAULT_CONNECT_TIMEOUT)
+    # @param debug [Boolean] Enable debug mode (defaults to POODLE_DEBUG env var or false)
+    # @param http_options [Hash] Additional HTTP client options
+    #
+    # @raise [ArgumentError] if api_key is missing or invalid
+    # @raise [ArgumentError] if base_url is invalid
+    # @raise [ArgumentError] if timeout values are invalid
+    def initialize(**options)
+      api_key = options[:api_key]
+      base_url = options[:base_url]
+      timeout = options[:timeout]
+      connect_timeout = options[:connect_timeout]
+      debug = options.fetch(:debug, false)
+      http_options = options.fetch(:http_options, {})
+      @api_key = api_key || ENV.fetch("POODLE_API_KEY", nil)
+      @base_url = base_url || ENV["POODLE_BASE_URL"] || DEFAULT_BASE_URL
+      @timeout = timeout || ENV.fetch("POODLE_TIMEOUT", DEFAULT_TIMEOUT).to_i
+      @connect_timeout = connect_timeout || ENV.fetch("POODLE_CONNECT_TIMEOUT", DEFAULT_CONNECT_TIMEOUT).to_i
+      @debug = debug || ENV["POODLE_DEBUG"] == "true"
+      @http_options = http_options
+
+      validate!
+    end
+
+    # Get the User-Agent string for HTTP requests
+    #
+    # @return [String] the User-Agent string
+    def user_agent
+      "poodle-ruby/#{SDK_VERSION} (Ruby #{RUBY_VERSION})"
+    end
+
+    # Get the full URL for an endpoint
+    #
+    # @param endpoint [String] the API endpoint
+    # @return [String] the full URL
+    def url_for(endpoint)
+      "#{@base_url}/#{endpoint.gsub(%r{^/}, '')}"
+    end
+
+    # Check if debug mode is enabled
+    #
+    # @return [Boolean] true if debug mode is enabled
+    def debug?
+      @debug
+    end
+
+    private
+
+    # Validate the configuration
+    #
+    # @raise [ArgumentError] if any configuration is invalid
+    def validate!
+      raise ArgumentError, "API key is required" if @api_key.nil? || @api_key.empty?
+
+      validate_url!(@base_url, "base_url")
+      validate_timeout!(@timeout, "timeout")
+      validate_timeout!(@connect_timeout, "connect_timeout")
+    end
+
+    # Validate a URL
+    #
+    # @param url [String] the URL to validate
+    # @param field [String] the field name for error messages
+    # @raise [ArgumentError] if the URL is invalid
+    def validate_url!(url, field)
+      return if url.nil? || url.empty?
+
+      uri = URI.parse(url)
+      raise ArgumentError, "#{field} must be a valid HTTP or HTTPS URL" unless %w[http https].include?(uri.scheme)
+    rescue URI::InvalidURIError
+      raise ArgumentError, "#{field} must be a valid URL"
+    end
+
+    # Validate a timeout value
+    #
+    # @param value [Integer] the timeout value
+    # @param field [String] the field name for error messages
+    # @raise [ArgumentError] if the timeout is invalid
+    def validate_timeout!(value, field)
+      raise ArgumentError, "#{field} must be a positive integer" unless value.is_a?(Integer) && value.positive?
+    end
+  end
+end

data/lib/poodle/email.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "configuration"
+require_relative "errors/validation_error"
+
+module Poodle
+  # Email model representing an email to be sent
+  #
+  # @example Creating an email
+  #   email = Poodle::Email.new(
+  #     from: "sender@example.com",
+  #     to: "recipient@example.com",
+  #     subject: "Hello World",
+  #     html: "<h1>Hello!</h1>",
+  #     text: "Hello!"
+  #   )
+  #
+  # @example HTML only email
+  #   email = Poodle::Email.new(
+  #     from: "sender@example.com",
+  #     to: "recipient@example.com",
+  #     subject: "Newsletter",
+  #     html: "<h1>Newsletter</h1><p>Content here</p>"
+  #   )
+  #
+  # @example Text only email
+  #   email = Poodle::Email.new(
+  #     from: "sender@example.com",
+  #     to: "recipient@example.com",
+  #     subject: "Simple notification",
+  #     text: "This is a simple text notification."
+  #   )
+  class Email
+    # @return [String] sender email address
+    attr_reader :from
+
+    # @return [String] recipient email address
+    attr_reader :to
+
+    # @return [String] email subject
+    attr_reader :subject
+
+    # @return [String, nil] HTML content
+    attr_reader :html
+
+    # @return [String, nil] plain text content
+    attr_reader :text
+
+    # Initialize a new Email
+    #
+    # @param from [String] sender email address
+    # @param to [String] recipient email address
+    # @param subject [String] email subject
+    # @param html [String, nil] HTML content
+    # @param text [String, nil] plain text content
+    #
+    # @raise [ValidationError] if any field is invalid
+    def initialize(from:, to:, subject:, html: nil, text: nil)
+      @from = from
+      @to = to
+      @subject = subject
+      @html = html
+      @text = text
+
+      validate!
+      freeze # Make the object immutable
+    end
+
+    # Convert email to hash for API request
+    #
+    # @return [Hash] email data as hash
+    def to_h
+      data = {
+        from: @from,
+        to: @to,
+        subject: @subject
+      }
+
+      data[:html] = @html if @html
+      data[:text] = @text if @text
+
+      data
+    end
+
+    # Convert email to JSON string
+    #
+    # @return [String] email data as JSON
+    def to_json(*args)
+      require "json"
+      to_h.to_json(*args)
+    end
+
+    # Check if email has HTML content
+    #
+    # @return [Boolean] true if HTML content is present
+    def html?
+      !@html.nil? && !@html.empty?
+    end
+
+    # Check if email has text content
+    #
+    # @return [Boolean] true if text content is present
+    def text?
+      !@text.nil? && !@text.empty?
+    end
+
+    # Check if email is multipart (has both HTML and text)
+    #
+    # @return [Boolean] true if both HTML and text content are present
+    def multipart?
+      html? && text?
+    end
+
+    # Get the size of the email content in bytes
+    #
+    # @return [Integer] total size of HTML and text content
+    def content_size
+      size = 0
+      size += @html.bytesize if @html
+      size += @text.bytesize if @text
+      size
+    end
+
+    private
+
+    # Validate email data
+    #
+    # @raise [ValidationError] if any validation fails
+    def validate!
+      validate_required_fields!
+      validate_email_addresses!
+      validate_content!
+      validate_content_size!
+    end
+
+    # Validate required fields
+    #
+    # @raise [ValidationError] if any required field is missing
+    def validate_required_fields!
+      raise ValidationError.missing_field("from") if @from.nil? || @from.empty?
+      raise ValidationError.missing_field("to") if @to.nil? || @to.empty?
+      raise ValidationError.missing_field("subject") if @subject.nil? || @subject.empty?
+    end
+
+    # Validate email addresses
+    #
+    # @raise [ValidationError] if any email address is invalid
+    def validate_email_addresses!
+      raise ValidationError.invalid_email(@from, field: "from") unless valid_email?(@from)
+      raise ValidationError.invalid_email(@to, field: "to") unless valid_email?(@to)
+    end
+
+    # Validate content presence
+    #
+    # @raise [ValidationError] if no content is provided
+    def validate_content!
+      return if html? || text?
+
+      raise ValidationError.invalid_content
+    end
+
+    # Validate content size
+    #
+    # @raise [ValidationError] if content is too large
+    def validate_content_size!
+      max_size = Configuration::MAX_CONTENT_SIZE
+
+      raise ValidationError.content_too_large("html", max_size) if @html && @html.bytesize > max_size
+
+      return unless @text && @text.bytesize > max_size
+
+      raise ValidationError.content_too_large("text", max_size)
+    end
+
+    # Check if an email address is valid
+    #
+    # @param email [String] the email address to validate
+    # @return [Boolean] true if the email is valid
+    def valid_email?(email)
+      return false if email.nil? || email.empty?
+
+      # Basic email validation using URI::MailTo
+      uri = URI::MailTo.build([email, nil])
+      uri.to_s == "mailto:#{email}"
+    rescue URI::InvalidComponentError, ArgumentError
+      false
+    end
+  end
+end