poodle-ruby 1.0.0

data/lib/poodle/rails.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require_relative "configuration"
+require_relative "client"
+
+module Poodle
+  # Rails integration module for Poodle SDK
+  #
+  # @example Rails initializer (config/initializers/poodle.rb)
+  #   Poodle::Rails.configure do |config|
+  #     config.api_key = Rails.application.credentials.poodle_api_key
+  #     config.debug = Rails.env.development?
+  #   end
+  #
+  # @example Using in Rails controllers
+  #   class NotificationController < ApplicationController
+  #     def send_welcome_email
+  #       response = Poodle::Rails.client.send(
+  #         from: "welcome@example.com",
+  #         to: params[:email],
+  #         subject: "Welcome!",
+  #         html: render_to_string("welcome_email")
+  #       )
+  #
+  #       if response.success?
+  #         render json: { status: "sent" }
+  #       else
+  #         render json: { error: response.message }, status: :unprocessable_entity
+  #       end
+  #     end
+  #   end
+  module Rails
+    class << self
+      # @return [Configuration, nil] the global configuration
+      attr_reader :configuration
+
+      # Configure Poodle for Rails applications
+      #
+      # @yield [Configuration] the configuration object
+      # @return [Configuration] the configuration object
+      #
+      # @example
+      #   Poodle::Rails.configure do |config|
+      #     config.api_key = Rails.application.credentials.poodle_api_key
+      #     config.base_url = "https://api.usepoodle.com"
+      #     config.timeout = 30
+      #     config.debug = Rails.env.development?
+      #   end
+      def configure
+        @configuration = Configuration.new
+        yield(@configuration) if block_given?
+        @configuration
+      end
+
+      # Get the global Poodle client for Rails
+      #
+      # @return [Client] the configured client
+      # @raise [RuntimeError] if not configured
+      #
+      # @example
+      #   client = Poodle::Rails.client
+      #   response = client.send(email_params)
+      def client
+        raise "Poodle not configured. Call Poodle::Rails.configure first." unless @configuration
+
+        @client ||= Client.new(@configuration)
+      end
+
+      # Reset the configuration and client (useful for testing)
+      #
+      # @return [void]
+      def reset!
+        @configuration = nil
+        @client = nil
+      end
+
+      # Check if Poodle is configured
+      #
+      # @return [Boolean] true if configured
+      def configured?
+        !@configuration.nil?
+      end
+
+      # Get configuration from Rails environment
+      #
+      # @return [Hash] configuration hash from Rails
+      def rails_config
+        return {} unless defined?(::Rails)
+
+        begin
+          ::Rails.application.config_for(:poodle)
+        rescue StandardError
+          {}
+        end
+      end
+
+      # Auto-configure from Rails credentials and environment
+      #
+      # @return [Configuration] the configuration object
+      #
+      # @example In Rails initializer
+      #   Poodle::Rails.auto_configure!
+      def auto_configure!
+        config_hash = rails_config
+
+        configure do |config|
+          configure_api_key(config, config_hash)
+          configure_base_url(config, config_hash)
+          configure_timeout(config, config_hash)
+          configure_debug_mode(config, config_hash)
+        end
+      end
+
+      private
+
+      # Configure API key from various sources
+      #
+      # @param config [Configuration] the configuration object
+      # @param config_hash [Hash] configuration from Rails
+      def configure_api_key(config, config_hash)
+        # Try Rails credentials first, then environment variables
+        if defined?(::Rails) && ::Rails.application.credentials.respond_to?(:poodle_api_key)
+          config.api_key = ::Rails.application.credentials.poodle_api_key
+        end
+
+        config.api_key ||= config_hash[:api_key] || ENV.fetch("POODLE_API_KEY", nil)
+      end
+
+      # Configure base URL from various sources
+      #
+      # @param config [Configuration] the configuration object
+      # @param config_hash [Hash] configuration from Rails
+      def configure_base_url(config, config_hash)
+        config.base_url = config_hash[:base_url] || ENV["POODLE_BASE_URL"] || config.base_url
+      end
+
+      # Configure timeout from various sources
+      #
+      # @param config [Configuration] the configuration object
+      # @param config_hash [Hash] configuration from Rails
+      def configure_timeout(config, config_hash)
+        config.timeout = config_hash[:timeout] || ENV["POODLE_TIMEOUT"]&.to_i || config.timeout
+      end
+
+      # Configure debug mode from various sources
+      #
+      # @param config [Configuration] the configuration object
+      # @param config_hash [Hash] configuration from Rails
+      def configure_debug_mode(config, config_hash)
+        config.debug = config_hash[:debug] || ENV["POODLE_DEBUG"] == "true" ||
+                       (defined?(::Rails) && ::Rails.env.development?)
+      end
+    end
+  end
+end
+
+# Auto-configure if Rails is detected
+require_relative "rails/railtie" if defined?(Rails)

data/lib/poodle/test_helpers.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require_relative "email_response"
+
+module Poodle
+  # Test utilities and mock classes for testing applications that use Poodle
+  #
+  # @example RSpec configuration
+  #   RSpec.configure do |config|
+  #     config.include Poodle::TestHelpers
+  #
+  #     config.before(:each) do
+  #       Poodle.test_mode!
+  #     end
+  #   end
+  #
+  # @example Testing email sending
+  #   it "sends welcome email" do
+  #     expect {
+  #       UserMailer.send_welcome(user)
+  #     }.to change { Poodle.deliveries.count }.by(1)
+  #
+  #     email = Poodle.deliveries.last
+  #     expect(email[:to]).to eq(user.email)
+  #     expect(email[:subject]).to include("Welcome")
+  #   end
+  module TestHelpers
+    # Mock client that captures emails instead of sending them
+    class MockClient
+      attr_reader :deliveries, :config
+
+      def initialize(config = nil)
+        @config = config || create_test_config
+        @deliveries = []
+      end
+
+      # Mock send method that captures email data
+      def send(from:, to:, subject:, html: nil, text: nil)
+        delivery = {
+          from: from,
+          to: to,
+          subject: subject,
+          html: html,
+          text: text,
+          sent_at: Time.now
+        }
+
+        @deliveries << delivery
+
+        EmailResponse.new(
+          success: true,
+          message: "Email queued for sending (test mode)",
+          data: { test_mode: true, delivery_id: @deliveries.length }
+        )
+      end
+
+      # Mock send_email method
+      def send_email(email)
+        if email.is_a?(Hash)
+          send(**email.transform_keys(&:to_sym))
+        else
+          send(
+            from: email.from,
+            to: email.to,
+            subject: email.subject,
+            html: email.html,
+            text: email.text
+          )
+        end
+      end
+
+      # Mock send_html method
+      def send_html(from:, to:, subject:, html:)
+        send(from: from, to: to, subject: subject, html: html)
+      end
+
+      # Mock send_text method
+      def send_text(from:, to:, subject:, text:)
+        send(from: from, to: to, subject: subject, text: text)
+      end
+
+      # Clear all captured deliveries
+      def clear_deliveries
+        @deliveries.clear
+      end
+
+      # Get the last delivery
+      def last_delivery
+        @deliveries.last
+      end
+
+      # Check if any emails were sent to a specific address
+      def sent_to?(email_address)
+        @deliveries.any? { |delivery| delivery[:to] == email_address }
+      end
+
+      # Get all deliveries sent to a specific address
+      def deliveries_to(email_address)
+        @deliveries.select { |delivery| delivery[:to] == email_address }
+      end
+
+      # Get all deliveries with a specific subject
+      def deliveries_with_subject(subject)
+        @deliveries.select { |delivery| delivery[:subject].include?(subject) }
+      end
+
+      # Get SDK version
+      def version
+        Poodle::VERSION
+      end
+
+      private
+
+      def create_test_config
+        # Create a simple configuration without triggering validation
+        config = Configuration.allocate
+        config.instance_variable_set(:@api_key, "test_key")
+        config.instance_variable_set(:@base_url, "https://api.usepoodle.com")
+        config.instance_variable_set(:@timeout, 30)
+        config.instance_variable_set(:@connect_timeout, 10)
+        config.instance_variable_set(:@debug, false)
+        config.instance_variable_set(:@http_options, {})
+        config
+      end
+    end
+
+    # Test mode configuration
+    module TestMode
+      class << self
+        attr_accessor :enabled
+
+        def enable!
+          @enabled = true
+        end
+
+        def disable!
+          @enabled = false
+          @mock_client = nil
+        end
+
+        def enabled?
+          @enabled == true
+        end
+
+        def mock_client
+          @mock_client ||= MockClient.new if enabled?
+        end
+
+        def deliveries
+          mock_client&.deliveries || []
+        end
+
+        def clear_deliveries
+          mock_client&.clear_deliveries
+        end
+
+        def last_delivery
+          mock_client&.last_delivery
+        end
+      end
+    end
+
+    # Helper methods for test assertions
+    module Assertions
+      # Assert that an email was sent
+      def assert_email_sent(count = 1)
+        actual_count = Poodle::TestHelpers::TestMode.deliveries.length
+        raise "Expected #{count} email(s) to be sent, but #{actual_count} were sent" unless actual_count == count
+      end
+
+      # Assert that an email was sent to a specific address
+      def assert_email_sent_to(email_address)
+        deliveries = Poodle::TestHelpers::TestMode.deliveries
+        sent = deliveries.any? { |delivery| delivery[:to] == email_address }
+        raise "Expected email to be sent to #{email_address}" unless sent
+      end
+
+      # Assert that an email was sent with a specific subject
+      def assert_email_sent_with_subject(subject)
+        deliveries = Poodle::TestHelpers::TestMode.deliveries
+        sent = deliveries.any? { |delivery| delivery[:subject].include?(subject) }
+        raise "Expected email to be sent with subject containing '#{subject}'" unless sent
+      end
+
+      # Assert that no emails were sent
+      def assert_no_emails_sent
+        count = Poodle::TestHelpers::TestMode.deliveries.length
+        raise "Expected no emails to be sent, but #{count} were sent" unless count.zero?
+      end
+    end
+
+    # Include assertion methods
+    include Assertions
+
+    # Convenience methods for accessing test data
+    def poodle_deliveries
+      Poodle::TestHelpers::TestMode.deliveries
+    end
+
+    def last_poodle_delivery
+      Poodle::TestHelpers::TestMode.last_delivery
+    end
+
+    def clear_poodle_deliveries
+      Poodle::TestHelpers::TestMode.clear_deliveries
+    end
+
+    # Create a mock client for testing
+    def poodle_mock_client
+      Poodle::TestHelpers::MockClient.new
+    end
+  end
+end
+
+# Convenience methods for global access
+module Poodle
+  def self.test_mode!
+    TestHelpers::TestMode.enable!
+  end
+
+  def self.disable_test_mode!
+    TestHelpers::TestMode.disable!
+  end
+
+  def self.test_mode?
+    TestHelpers::TestMode.enabled?
+  end
+
+  def self.deliveries
+    TestHelpers::TestMode.deliveries
+  end
+
+  def self.clear_deliveries
+    TestHelpers::TestMode.clear_deliveries
+  end
+
+  def self.last_delivery
+    TestHelpers::TestMode.last_delivery
+  end
+
+  def self.mock_client
+    TestHelpers::MockClient.new
+  end
+end

data/lib/poodle/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Poodle
+  # The current version of the Poodle Ruby SDK
+  VERSION = "1.0.0"
+end

data/lib/poodle.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require_relative "poodle/version"
+require_relative "poodle/configuration"
+require_relative "poodle/email"
+require_relative "poodle/email_response"
+require_relative "poodle/client"
+
+# Error classes
+require_relative "poodle/errors/base_error"
+require_relative "poodle/errors/validation_error"
+require_relative "poodle/errors/authentication_error"
+require_relative "poodle/errors/payment_error"
+require_relative "poodle/errors/forbidden_error"
+require_relative "poodle/errors/rate_limit_error"
+require_relative "poodle/errors/network_error"
+require_relative "poodle/errors/server_error"
+
+# Additional modules (loaded on demand)
+# require_relative "poodle/test_helpers"
+
+# Rails integration (optional)
+begin
+  require_relative "poodle/rails" if defined?(Rails)
+rescue LoadError
+  # Rails not available, skip Rails integration
+end
+
+# Ruby SDK for the Poodle email sending API
+#
+# @example Quick start
+#   require "poodle"
+#
+#   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>"
+#   )
+#
+#   puts "Email sent!" if response.success?
+#
+# @example Using environment variables
+#   ENV["POODLE_API_KEY"] = "your_api_key"
+#   client = Poodle::Client.new
+#
+# @example Error handling
+#   begin
+#     response = client.send(email_data)
+#   rescue Poodle::ValidationError => e
+#     puts "Validation failed: #{e.errors}"
+#   rescue Poodle::AuthenticationError => e
+#     puts "Authentication failed: #{e.message}"
+#   rescue Poodle::RateLimitError => e
+#     puts "Rate limited. Retry after: #{e.retry_after} seconds"
+#   rescue Poodle::Error => e
+#     puts "Poodle error: #{e.message}"
+#   end
+module Poodle
+  # Convenience method to create a new client
+  #
+  # @param args [Array] arguments to pass to Client.new
+  # @param kwargs [Hash] keyword arguments to pass to Client.new
+  # @return [Client] a new client instance
+  #
+  # @example
+  #   client = Poodle.new(api_key: "your_api_key")
+  #   # equivalent to: Poodle::Client.new(api_key: "your_api_key")
+  def self.new(*args, **kwargs)
+    Client.new(*args, **kwargs)
+  end
+
+  # Get the SDK version
+  #
+  # @return [String] the SDK version
+  def self.version
+    VERSION
+  end
+end

data/sig/poodle.rbs

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

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: poodle-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Wilbert Liu
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-05-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Ruby SDK for the Poodle email sending API
+email:
+- wilbert@usepoodle.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".yardopts"
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE
+- README.md
+- Rakefile
+- examples/advanced_usage.rb
+- examples/basic_usage.rb
+- lib/poodle.rb
+- lib/poodle/client.rb
+- lib/poodle/configuration.rb
+- lib/poodle/email.rb
+- lib/poodle/email_response.rb
+- lib/poodle/errors/authentication_error.rb
+- lib/poodle/errors/base_error.rb
+- lib/poodle/errors/forbidden_error.rb
+- lib/poodle/errors/network_error.rb
+- lib/poodle/errors/payment_error.rb
+- lib/poodle/errors/rate_limit_error.rb
+- lib/poodle/errors/server_error.rb
+- lib/poodle/errors/validation_error.rb
+- lib/poodle/http_client.rb
+- lib/poodle/rails.rb
+- lib/poodle/rails/railtie.rb
+- lib/poodle/rails/tasks.rake
+- lib/poodle/test_helpers.rb
+- lib/poodle/version.rb
+- sig/poodle.rbs
+homepage: https://usepoodle.com
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://usepoodle.com
+  source_code_uri: https://github.com/usepoodle/poodle-ruby
+  documentation_uri: https://rubydoc.info/gems/poodle-ruby
+  bug_tracker_uri: https://github.com/usepoodle/poodle-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Poodle Ruby SDK
+test_files: []