poodle-ruby 1.0.0

data/lib/poodle/email_response.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Poodle
+  # Email response model representing the API response for email operations
+  #
+  # @example Checking response status
+  #   response = client.send_email(email)
+  #   if response.success?
+  #     puts "Email sent: #{response.message}"
+  #   else
+  #     puts "Failed: #{response.message}"
+  #   end
+  #
+  # @example Converting to hash
+  #   response_data = response.to_h
+  #   puts response_data[:success]
+  #   puts response_data[:message]
+  class EmailResponse
+    # @return [Boolean] whether the email was successfully queued
+    attr_reader :success
+
+    # @return [String] response message from the API
+    attr_reader :message
+
+    # @return [Hash] additional response data
+    attr_reader :data
+
+    # Initialize a new EmailResponse
+    #
+    # @param success [Boolean] whether the operation was successful
+    # @param message [String] response message
+    # @param data [Hash] additional response data
+    def initialize(success:, message:, data: {})
+      @success = success
+      @message = message
+      @data = data
+      freeze # Make the object immutable
+    end
+
+    # Create an EmailResponse from API response data
+    #
+    # @param response_data [Hash] the API response data
+    # @return [EmailResponse] the email response object
+    def self.from_api_response(response_data)
+      new(
+        success: response_data[:success] || response_data["success"] || false,
+        message: response_data[:message] || response_data["message"] || "",
+        data: response_data
+      )
+    end
+
+    # Check if email was successfully queued
+    #
+    # @return [Boolean] true if successful
+    def success?
+      @success
+    end
+
+    # Check if email sending failed
+    #
+    # @return [Boolean] true if failed
+    def failed?
+      !@success
+    end
+
+    # Convert response to hash
+    #
+    # @return [Hash] response data as hash
+    def to_h
+      {
+        success: @success,
+        message: @message,
+        data: @data
+      }
+    end
+
+    # Convert response to JSON string
+    #
+    # @return [String] response data as JSON
+    def to_json(*args)
+      require "json"
+      to_h.to_json(*args)
+    end
+
+    # Get a string representation of the response
+    #
+    # @return [String] formatted response information
+    def to_s
+      status = @success ? "SUCCESS" : "FAILED"
+      "EmailResponse[#{status}]: #{@message}"
+    end
+
+    # Get detailed string representation for debugging
+    #
+    # @return [String] detailed response information
+    def inspect
+      "#<#{self.class.name}:0x#{object_id.to_s(16)} " \
+        "success=#{@success} message=#{@message.inspect} data=#{@data.inspect}>"
+    end
+  end
+end

data/lib/poodle/errors/authentication_error.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "base_error"
+
+module Poodle
+  # Exception raised when API authentication fails (401 Unauthorized)
+  #
+  # @example Handling authentication errors
+  #   begin
+  #     client.send_email(email)
+  #   rescue Poodle::AuthenticationError => e
+  #     puts "Authentication failed: #{e.message}"
+  #     puts "Please check your API key"
+  #   end
+  class AuthenticationError < Error
+    # Initialize a new AuthenticationError
+    #
+    # @param message [String] the error message
+    # @param context [Hash] additional context information
+    def initialize(message = "Authentication failed", context: {})
+      super(message, context: context, status_code: 401)
+    end
+
+    # Create an AuthenticationError for invalid API key
+    #
+    # @return [AuthenticationError] the authentication error
+    def self.invalid_api_key
+      new(
+        "Invalid API key provided. Please check your API key and try again.",
+        context: { error_type: "invalid_api_key" }
+      )
+    end
+
+    # Create an AuthenticationError for missing API key
+    #
+    # @return [AuthenticationError] the authentication error
+    def self.missing_api_key
+      new(
+        "API key is required. Please provide a valid API key.",
+        context: { error_type: "missing_api_key" }
+      )
+    end
+
+    # Create an AuthenticationError for expired API key
+    #
+    # @return [AuthenticationError] the authentication error
+    def self.expired_api_key
+      new(
+        "API key has expired. Please generate a new API key.",
+        context: { error_type: "expired_api_key" }
+      )
+    end
+  end
+end

data/lib/poodle/errors/base_error.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Poodle
+  # Base exception class for all Poodle SDK errors
+  #
+  # @example Catching all Poodle errors
+  #   begin
+  #     client.send_email(email)
+  #   rescue Poodle::Error => e
+  #     puts "Poodle error: #{e.message}"
+  #     puts "Context: #{e.context}"
+  #   end
+  class Error < StandardError
+    # @return [Hash] additional context information about the error
+    attr_reader :context
+
+    # @return [Integer, nil] HTTP status code if available
+    attr_reader :status_code
+
+    # Initialize a new error
+    #
+    # @param message [String] the error message
+    # @param context [Hash] additional context information
+    # @param status_code [Integer, nil] HTTP status code
+    def initialize(message = "", context: {}, status_code: nil)
+      @original_message = message
+      super(message)
+      @context = context
+      @status_code = status_code
+    end
+
+    # Get the original error message without formatting
+    #
+    # @return [String] the original error message
+    def message
+      @original_message
+    end
+
+    # Get a string representation of the error with context
+    #
+    # @return [String] formatted error information
+    def to_s
+      result = @original_message
+      result += " (Status: #{@status_code})" if @status_code
+      result += " Context: #{@context}" unless @context.empty?
+      result
+    end
+  end
+end

data/lib/poodle/errors/forbidden_error.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "base_error"
+
+module Poodle
+  # Exception raised when access is forbidden (403 Forbidden)
+  #
+  # @example Handling forbidden errors
+  #   begin
+  #     client.send_email(email)
+  #   rescue Poodle::ForbiddenError => e
+  #     puts "Access forbidden: #{e.message}"
+  #     puts "Reason: #{e.reason}" if e.reason
+  #   end
+  class ForbiddenError < Error
+    # @return [String, nil] reason for the forbidden access
+    attr_reader :reason
+
+    # Initialize a new ForbiddenError
+    #
+    # @param message [String] the error message
+    # @param reason [String, nil] reason for the forbidden access
+    # @param context [Hash] additional context information
+    def initialize(message = "Access forbidden", reason: nil, context: {})
+      @reason = reason
+      super(message, context: context.merge(reason: reason), status_code: 403)
+    end
+
+    # Create a ForbiddenError for account suspended
+    #
+    # @param reason [String] the suspension reason
+    # @param rate [Float, nil] the suspension rate if applicable
+    # @return [ForbiddenError] the forbidden error
+    def self.account_suspended(reason, rate = nil)
+      message = "Account suspended: #{reason}"
+      message += " (Rate: #{rate})" if rate
+
+      new(
+        message,
+        reason: reason,
+        context: { error_type: "account_suspended", suspension_rate: rate }
+      )
+    end
+
+    # Create a ForbiddenError for insufficient permissions
+    #
+    # @return [ForbiddenError] the forbidden error
+    def self.insufficient_permissions
+      new(
+        "API key does not have sufficient permissions for this operation.",
+        reason: "insufficient_permissions",
+        context: { error_type: "insufficient_permissions" }
+      )
+    end
+  end
+end

data/lib/poodle/errors/network_error.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "base_error"
+
+module Poodle
+  # Exception raised when network or HTTP errors occur
+  #
+  # @example Handling network errors
+  #   begin
+  #     client.send_email(email)
+  #   rescue Poodle::NetworkError => e
+  #     puts "Network error: #{e.message}"
+  #     puts "Original error: #{e.original_error}" if e.original_error
+  #   end
+  class NetworkError < Error
+    # @return [Exception, nil] the original exception that caused this error
+    attr_reader :original_error
+
+    # Initialize a new NetworkError
+    #
+    # @param message [String] the error message
+    # @param original_error [Exception, nil] the original exception
+    # @param context [Hash] additional context information
+    # @param status_code [Integer, nil] HTTP status code
+    def initialize(message = "Network error occurred", original_error: nil, context: {}, status_code: nil)
+      @original_error = original_error
+      super(message, context: context, status_code: status_code)
+    end
+
+    # Create a NetworkError for connection timeout
+    #
+    # @param timeout [Integer] the timeout duration
+    # @return [NetworkError] the network error
+    def self.connection_timeout(timeout)
+      new(
+        "Connection timeout after #{timeout} seconds",
+        context: { timeout: timeout, error_type: "connection_timeout" },
+        status_code: 408
+      )
+    end
+
+    # Create a NetworkError for connection failure
+    #
+    # @param url [String] the URL that failed to connect
+    # @param original_error [Exception, nil] the original exception
+    # @return [NetworkError] the network error
+    def self.connection_failed(url, original_error: nil)
+      new(
+        "Failed to connect to #{url}",
+        original_error: original_error,
+        context: { url: url, error_type: "connection_failed" }
+      )
+    end
+
+    # Create a NetworkError for DNS resolution failure
+    #
+    # @param host [String] the host that failed to resolve
+    # @return [NetworkError] the network error
+    def self.dns_resolution_failed(host)
+      new(
+        "DNS resolution failed for host: #{host}",
+        context: { host: host, error_type: "dns_resolution_failed" }
+      )
+    end
+
+    # Create a NetworkError for SSL/TLS errors
+    #
+    # @param message [String] the SSL error message
+    # @return [NetworkError] the network error
+    def self.ssl_error(message)
+      new(
+        "SSL/TLS error: #{message}",
+        context: { error_type: "ssl_error" }
+      )
+    end
+
+    # Create a NetworkError for HTTP errors
+    #
+    # @param status_code [Integer] the HTTP status code
+    # @param message [String] the error message
+    # @return [NetworkError] the network error
+    def self.http_error(status_code, message = "")
+      default_message = "HTTP error occurred with status code: #{status_code}"
+      final_message = message.empty? ? default_message : message
+
+      new(
+        final_message,
+        context: { error_type: "http_error" },
+        status_code: status_code
+      )
+    end
+
+    # Create a NetworkError for malformed response
+    #
+    # @param response [String] the malformed response
+    # @return [NetworkError] the network error
+    def self.malformed_response(response = "")
+      new(
+        "Received malformed response from server",
+        context: { response: response, error_type: "malformed_response" }
+      )
+    end
+  end
+end

data/lib/poodle/errors/payment_error.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "base_error"
+
+module Poodle
+  # Exception raised when payment is required (402 Payment Required)
+  #
+  # @example Handling payment errors
+  #   begin
+  #     client.send_email(email)
+  #   rescue Poodle::PaymentError => e
+  #     puts "Payment required: #{e.message}"
+  #     puts "Upgrade URL: #{e.upgrade_url}" if e.upgrade_url
+  #   end
+  class PaymentError < Error
+    # @return [String, nil] URL to upgrade subscription
+    attr_reader :upgrade_url
+
+    # Initialize a new PaymentError
+    #
+    # @param message [String] the error message
+    # @param upgrade_url [String, nil] URL to upgrade subscription
+    # @param context [Hash] additional context information
+    def initialize(message = "Payment required", upgrade_url: nil, context: {})
+      @upgrade_url = upgrade_url
+      super(message, context: context.merge(upgrade_url: upgrade_url), status_code: 402)
+    end
+
+    # Create a PaymentError for subscription expired
+    #
+    # @return [PaymentError] the payment error
+    def self.subscription_expired
+      new(
+        "Subscription expired. Please renew your subscription to continue sending emails.",
+        upgrade_url: "https://app.usepoodle.com/upgrade",
+        context: { error_type: "subscription_expired" }
+      )
+    end
+
+    # Create a PaymentError for trial limit reached
+    #
+    # @return [PaymentError] the payment error
+    def self.trial_limit_reached
+      new(
+        "Trial limit reached. Please upgrade to a paid plan to continue sending emails.",
+        upgrade_url: "https://app.usepoodle.com/upgrade",
+        context: { error_type: "trial_limit_reached" }
+      )
+    end
+
+    # Create a PaymentError for monthly limit reached
+    #
+    # @return [PaymentError] the payment error
+    def self.monthly_limit_reached
+      new(
+        "Monthly email limit reached. Please upgrade your plan to send more emails.",
+        upgrade_url: "https://app.usepoodle.com/upgrade",
+        context: { error_type: "monthly_limit_reached" }
+      )
+    end
+
+    # Create a PaymentError for monthly limit exceeded (alias for monthly_limit_reached)
+    #
+    # @return [PaymentError] the payment error
+    def self.monthly_limit_exceeded
+      new(
+        "Monthly email limit exceeded. Please upgrade your plan to send more emails.",
+        upgrade_url: "https://app.usepoodle.com/upgrade",
+        context: { error_type: "monthly_limit_exceeded" }
+      )
+    end
+  end
+end

data/lib/poodle/errors/rate_limit_error.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "base_error"
+
+module Poodle
+  # Exception raised when API rate limits are exceeded (429 Too Many Requests)
+  #
+  # @example Handling rate limit errors
+  #   begin
+  #     client.send_email(email)
+  #   rescue Poodle::RateLimitError => e
+  #     puts "Rate limit exceeded: #{e.message}"
+  #     puts "Retry after: #{e.retry_after} seconds" if e.retry_after
+  #     puts "Limit: #{e.limit}, Remaining: #{e.remaining}"
+  #   end
+  class RateLimitError < Error
+    # @return [Integer, nil] seconds to wait before retrying
+    attr_reader :retry_after
+
+    # @return [Integer, nil] the rate limit
+    attr_reader :limit
+
+    # @return [Integer, nil] remaining requests
+    attr_reader :remaining
+
+    # @return [Integer, nil] time when the rate limit resets
+    attr_reader :reset_time
+
+    # Initialize a new RateLimitError
+    #
+    # @param message [String] the error message
+    # @param retry_after [Integer, nil] seconds to wait before retrying
+    # @param limit [Integer, nil] the rate limit
+    # @param remaining [Integer, nil] remaining requests
+    # @param reset_time [Integer, nil] time when the rate limit resets
+    # @param context [Hash] additional context information
+    def initialize(message = "Rate limit exceeded", **options)
+      @retry_after = options[:retry_after]
+      @limit = options[:limit]
+      @remaining = options[:remaining]
+      @reset_time = options[:reset_time]
+      context = options.fetch(:context, {})
+
+      rate_context = {
+        error_type: "rate_limit_exceeded",
+        retry_after: @retry_after,
+        limit: @limit,
+        remaining: @remaining,
+        reset_time: @reset_time
+      }.compact
+
+      super(message, context: context.merge(rate_context), status_code: 429)
+    end
+
+    # Create a RateLimitError from response headers
+    #
+    # @param headers [Hash] HTTP response headers
+    # @return [RateLimitError] the rate limit error
+    def self.from_headers(headers)
+      retry_after = extract_retry_after(headers)
+      limit = extract_limit(headers)
+      remaining = extract_remaining(headers)
+      reset_time = extract_reset_time(headers)
+
+      message = build_message(retry_after)
+      context = build_context(limit, remaining, reset_time)
+
+      new(
+        message,
+        retry_after: retry_after,
+        limit: limit&.to_i,
+        remaining: remaining&.to_i,
+        reset_time: reset_time&.to_i,
+        context: context
+      )
+    end
+
+    # Extract retry-after value from headers
+    #
+    # @param headers [Hash] HTTP response headers
+    # @return [Integer, nil] retry after seconds
+    def self.extract_retry_after(headers)
+      headers["retry-after"]&.to_i
+    end
+
+    # Extract rate limit from headers
+    #
+    # @param headers [Hash] HTTP response headers
+    # @return [String, nil] rate limit value
+    def self.extract_limit(headers)
+      headers["X-RateLimit-Limit"] || headers["ratelimit-limit"]
+    end
+
+    # Extract remaining requests from headers
+    #
+    # @param headers [Hash] HTTP response headers
+    # @return [String, nil] remaining requests value
+    def self.extract_remaining(headers)
+      headers["X-RateLimit-Remaining"] || headers["ratelimit-remaining"]
+    end
+
+    # Extract reset time from headers
+    #
+    # @param headers [Hash] HTTP response headers
+    # @return [String, nil] reset time value
+    def self.extract_reset_time(headers)
+      headers["X-RateLimit-Reset"] || headers["ratelimit-reset"]
+    end
+
+    # Build error message
+    #
+    # @param retry_after [Integer, nil] retry after seconds
+    # @return [String] error message
+    def self.build_message(retry_after)
+      message = "Rate limit exceeded."
+      message += " Retry after #{retry_after} seconds." if retry_after
+      message
+    end
+
+    # Build context hash
+    #
+    # @param limit [String, nil] rate limit
+    # @param remaining [String, nil] remaining requests
+    # @param reset_time [String, nil] reset time
+    # @return [Hash] context hash
+    def self.build_context(limit, remaining, reset_time)
+      {
+        limit: limit,
+        remaining: remaining,
+        reset_at: reset_time
+      }.compact
+    end
+
+    private_class_method :extract_retry_after, :extract_limit, :extract_remaining,
+                         :extract_reset_time, :build_message, :build_context
+
+    # Get the time when the rate limit resets as a Time object
+    #
+    # @return [Time, nil] the reset time
+    def reset_at
+      return nil unless @reset_time
+
+      Time.at(@reset_time)
+    end
+  end
+end

data/lib/poodle/errors/server_error.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "base_error"
+
+module Poodle
+  # Exception raised when server errors occur (5xx status codes)
+  #
+  # @example Handling server errors
+  #   begin
+  #     client.send_email(email)
+  #   rescue Poodle::ServerError => e
+  #     puts "Server error: #{e.message}"
+  #     puts "Status code: #{e.status_code}"
+  #   end
+  class ServerError < Error
+    # Initialize a new ServerError
+    #
+    # @param message [String] the error message
+    # @param context [Hash] additional context information
+    # @param status_code [Integer] HTTP status code (5xx)
+    def initialize(message = "Server error occurred", context: {}, status_code: 500)
+      super(message, context: context.merge(error_type: "server_error"), status_code: status_code)
+    end
+
+    # Create a ServerError for internal server error
+    #
+    # @param message [String] the error message
+    # @return [ServerError] the server error
+    def self.internal_server_error(message = "Internal server error")
+      new(message, status_code: 500)
+    end
+
+    # Create a ServerError for bad gateway
+    #
+    # @param message [String] the error message
+    # @return [ServerError] the server error
+    def self.bad_gateway(message = "Bad gateway")
+      new(message, status_code: 502)
+    end
+
+    # Create a ServerError for service unavailable
+    #
+    # @param message [String] the error message
+    # @return [ServerError] the server error
+    def self.service_unavailable(message = "Service unavailable")
+      new(message, status_code: 503)
+    end
+
+    # Create a ServerError for gateway timeout
+    #
+    # @param message [String] the error message
+    # @return [ServerError] the server error
+    def self.gateway_timeout(message = "Gateway timeout")
+      new(message, status_code: 504)
+    end
+  end
+end