poodle-ruby 1.0.0

data/README.md

@@ -0,0 +1,442 @@
+# Poodle Ruby SDK
+
+[![Gem Version](https://badge.fury.io/rb/poodle-ruby.svg)](https://badge.fury.io/rb/poodle-ruby)
+[![Build Status](https://github.com/usepoodle/poodle-ruby/workflows/CI/badge.svg)](https://github.com/usepoodle/poodle-ruby/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+Ruby SDK for the Poodle's email sending API.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Configuration](#configuration)
+- [Usage Examples](#usage-examples)
+- [API Reference](#api-reference)
+- [Error Types](#error-types)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Support](#support)
+
+## Features
+
+- 🚀 **Simple API** - Send emails with just a few lines of code
+- 🔒 **Type Safe** - Comprehensive validation and error handling
+- 🌐 **Environment Support** - Easy configuration via environment variables
+- 📝 **Rich Content** - Support for HTML, plain text, and multipart emails
+- 🔄 **Retry Logic** - Built-in support for handling rate limits and network issues
+- 🧪 **Test Support** - Comprehensive testing utilities and mocks
+- 📚 **Well Documented** - Comprehensive documentation and examples
+- 🎯 **Ruby 3.0+** - Modern Ruby support with keyword arguments
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'poodle-ruby'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install poodle-ruby
+```
+
+## Quick Start
+
+```ruby
+require 'poodle'
+
+# Initialize the client
+client = Poodle::Client.new(api_key: 'your_api_key')
+
+# Send an email
+response = client.send(
+  from: 'sender@example.com',
+  to: 'recipient@example.com',
+  subject: 'Hello from Poodle!',
+  html: '<h1>Hello World!</h1><p>This email was sent using Poodle.</p>'
+)
+
+if response.success?
+  puts "Email sent successfully!"
+else
+  puts "Failed to send email: #{response.message}"
+end
+```
+
+## Configuration
+
+### API Key
+
+Set your API key in one of these ways:
+
+```ruby
+# 1. Pass directly to client
+client = Poodle::Client.new(api_key: 'your_api_key')
+
+# 2. Use environment variable
+ENV['POODLE_API_KEY'] = 'your_api_key'
+client = Poodle::Client.new
+
+# 3. Use configuration object
+config = Poodle::Configuration.new(
+  api_key: 'your_api_key',
+  timeout: 30,
+  debug: true
+)
+client = Poodle::Client.new(config)
+```
+
+### Environment Variables
+
+| Variable                 | Description                   | Default                     |
+| ------------------------ | ----------------------------- | --------------------------- |
+| `POODLE_API_KEY`         | Your Poodle API key           | Required                    |
+| `POODLE_BASE_URL`        | API base URL                  | `https://api.usepoodle.com` |
+| `POODLE_TIMEOUT`         | Request timeout in seconds    | `30`                        |
+| `POODLE_CONNECT_TIMEOUT` | Connection timeout in seconds | `10`                        |
+| `POODLE_DEBUG`           | Enable debug logging          | `false`                     |
+
+## Usage Examples
+
+### Basic Email Sending
+
+```ruby
+# HTML email
+response = client.send_html(
+  from: 'newsletter@example.com',
+  to: 'subscriber@example.com',
+  subject: 'Weekly Newsletter',
+  html: '<h1>Newsletter</h1><p>Your weekly update...</p>'
+)
+
+# Plain text email
+response = client.send_text(
+  from: 'notifications@example.com',
+  to: 'user@example.com',
+  subject: 'Account Update',
+  text: 'Your account has been updated successfully.'
+)
+
+# Multipart email (HTML + Text)
+response = client.send(
+  from: 'support@example.com',
+  to: 'customer@example.com',
+  subject: 'Welcome!',
+  html: '<h1>Welcome!</h1><p>Thanks for joining us.</p>',
+  text: 'Welcome! Thanks for joining us.'
+)
+```
+
+### Using Email Objects
+
+```ruby
+# Create an Email object for reusability and validation
+email = Poodle::Email.new(
+  from: 'sender@example.com',
+  to: 'recipient@example.com',
+  subject: 'Important Update',
+  html: '<h1>Update</h1><p>Please read this important update.</p>',
+  text: 'Update: Please read this important update.'
+)
+
+# Check email properties
+puts "Multipart email: #{email.multipart?}"
+puts "Content size: #{email.content_size} bytes"
+
+# Send the email
+response = client.send_email(email)
+```
+
+### Multipart Emails (HTML + Text)
+
+```ruby
+# Send emails with both HTML and text content for maximum compatibility
+response = client.send(
+  from: 'newsletter@example.com',
+  to: 'subscriber@example.com',
+  subject: 'Weekly Newsletter',
+  html: '<h1>Newsletter</h1><p>This week\'s updates...</p>',
+  text: 'Newsletter\n\nThis week\'s updates...'
+)
+```
+
+### Rails Integration
+
+The Poodle SDK provides seamless Rails integration with automatic configuration and helpful rake tasks.
+
+#### Installation
+
+Add to your Rails application's Gemfile:
+
+```ruby
+gem 'poodle-ruby'
+```
+
+#### Configuration
+
+Create an initializer or let Poodle auto-configure:
+
+```ruby
+# config/initializers/poodle.rb
+Poodle::Rails.configure do |config|
+  config.api_key = Rails.application.credentials.poodle_api_key
+  config.debug = Rails.env.development?
+end
+```
+
+Or use environment variables:
+
+```bash
+# .env or environment
+POODLE_API_KEY=your_api_key_here
+```
+
+#### Usage in Controllers
+
+```ruby
+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
+```
+
+#### Rake Tasks
+
+```bash
+# Check configuration
+rake poodle:config
+
+# Test connection
+rake poodle:test
+
+# Send test email
+rake poodle:send_test[recipient@example.com]
+
+# Generate initializer
+rake poodle:install
+```
+
+### Testing
+
+The SDK includes comprehensive testing utilities for easy testing in your applications.
+
+#### RSpec Integration
+
+```ruby
+# spec/spec_helper.rb or spec/rails_helper.rb
+require 'poodle'
+
+RSpec.configure do |config|
+  config.include Poodle::TestHelpers
+
+  config.before(:each) do
+    Poodle.test_mode!
+  end
+
+  config.after(:each) do
+    Poodle.clear_deliveries
+  end
+end
+```
+
+#### Testing Email Sending
+
+```ruby
+it "sends welcome email" do
+  expect {
+    UserMailer.send_welcome(user)
+  }.to change { Poodle.deliveries.count }.by(1)
+
+  email = Poodle.last_delivery
+  expect(email[:to]).to eq(user.email)
+  expect(email[:subject]).to include("Welcome")
+  expect(email[:html]).to include(user.name)
+end
+
+it "sends notification emails" do
+  service.send_notifications
+
+  assert_email_sent(3)
+  assert_email_sent_to("admin@example.com")
+  assert_email_sent_with_subject("Alert")
+end
+```
+
+### Error Handling
+
+```ruby
+begin
+  response = client.send(email_data)
+  puts "Email sent!" if response.success?
+rescue Poodle::ValidationError => e
+  puts "Validation failed: #{e.message}"
+  e.errors.each do |field, messages|
+    puts "#{field}: #{messages.join(', ')}"
+  end
+rescue Poodle::AuthenticationError => e
+  puts "Authentication failed: #{e.message}"
+rescue Poodle::RateLimitError => e
+  puts "Rate limited. Retry after: #{e.retry_after} seconds"
+rescue Poodle::PaymentError => e
+  puts "Payment required: #{e.message}"
+  puts "Upgrade at: #{e.upgrade_url}"
+rescue Poodle::ForbiddenError => e
+  puts "Access forbidden: #{e.message}"
+rescue Poodle::NetworkError => e
+  puts "Network error: #{e.message}"
+rescue Poodle::ServerError => e
+  puts "Server error: #{e.message}"
+rescue Poodle::Error => e
+  puts "Poodle error: #{e.message}"
+end
+```
+
+### Retry Logic
+
+```ruby
+def send_with_retry(client, email_data, max_retries: 3)
+  retries = 0
+
+  begin
+    client.send(email_data)
+  rescue Poodle::RateLimitError => e
+    if retries < max_retries && e.retry_after
+      retries += 1
+      sleep(e.retry_after)
+      retry
+    else
+      raise
+    end
+  rescue Poodle::NetworkError, Poodle::ServerError => e
+    if retries < max_retries
+      retries += 1
+      sleep(2 ** retries) # Exponential backoff
+      retry
+    else
+      raise
+    end
+  end
+end
+```
+
+## API Reference
+
+### Client
+
+#### `Poodle::Client.new(config_or_api_key, **options)`
+
+Creates a new Poodle client.
+
+**Parameters:**
+
+- `config_or_api_key` - Configuration object, API key string, or nil
+- `**options` - Additional options (base_url, timeout, debug, etc.)
+
+#### `client.send(from:, to:, subject:, html: nil, text: nil)`
+
+Sends an email with the specified parameters.
+
+#### `client.send_email(email)`
+
+Sends an Email object.
+
+#### `client.send_html(from:, to:, subject:, html:)`
+
+Sends an HTML-only email.
+
+#### `client.send_text(from:, to:, subject:, text:)`
+
+Sends a text-only email.
+
+### Email
+
+#### `Poodle::Email.new(from:, to:, subject:, html: nil, text: nil)`
+
+Creates a new Email object with validation.
+
+**Methods:**
+
+- `#html?` - Returns true if HTML content is present
+- `#text?` - Returns true if text content is present
+- `#multipart?` - Returns true if both HTML and text are present
+- `#content_size` - Returns total content size in bytes
+- `#to_h` - Converts to hash for API requests
+
+### EmailResponse
+
+#### Properties
+
+- `#success?` - Returns true if email was successfully queued
+- `#failed?` - Returns true if email sending failed
+- `#message` - Response message from API
+- `#data` - Additional response data
+
+### Configuration
+
+#### `Poodle::Configuration.new(**options)`
+
+Creates a new configuration object.
+
+**Options:**
+
+- `api_key` - Your Poodle API key
+- `base_url` - API base URL
+- `timeout` - Request timeout in seconds
+- `connect_timeout` - Connection timeout in seconds
+- `debug` - Enable debug logging
+- `http_options` - Additional HTTP client options
+
+## Error Types
+
+| Error Class                   | Description              | HTTP Status |
+| ----------------------------- | ------------------------ | ----------- |
+| `Poodle::ValidationError`     | Invalid request data     | 400, 422    |
+| `Poodle::AuthenticationError` | Invalid API key          | 401         |
+| `Poodle::PaymentError`        | Payment required         | 402         |
+| `Poodle::ForbiddenError`      | Access forbidden         | 403         |
+| `Poodle::RateLimitError`      | Rate limit exceeded      | 429         |
+| `Poodle::ServerError`         | Server error             | 5xx         |
+| `Poodle::NetworkError`        | Network/connection error | Various     |
+
+All errors inherit from `Poodle::Error` which provides:
+
+- `#message` - Error message
+- `#context` - Additional error context
+- `#status_code` - HTTP status code (if applicable)
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on the process for submitting pull requests and our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+task default: %i[]

data/examples/advanced_usage.rb

@@ -0,0 +1,255 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "poodle"
+
+# Advanced usage example for the Poodle Ruby SDK
+
+# Example 1: Using configuration object
+puts "=== Example 1: Configuration Object ==="
+
+config = Poodle::Configuration.new(
+  api_key: "your_api_key_here",
+  base_url: "https://api.usepoodle.com",
+  timeout: 60,
+  debug: true
+)
+
+client = Poodle::Client.new(config)
+puts "Client initialized with custom configuration"
+puts "User-Agent: #{config.user_agent}"
+puts "Base URL: #{config.base_url}"
+
+# Example 2: Using Email objects
+puts "\n=== Example 2: Email Objects ==="
+
+begin
+  # Create an Email object
+  email = Poodle::Email.new(
+    from: "newsletter@example.com",
+    to: "subscriber@example.com",
+    subject: "Weekly Newsletter - #{Date.today}",
+    html: <<~HTML,
+      <html>
+        <body>
+          <h1>Weekly Newsletter</h1>
+          <p>Welcome to our weekly newsletter!</p>
+          <ul>
+            <li>Feature 1: New dashboard</li>
+            <li>Feature 2: Improved performance</li>
+            <li>Feature 3: Bug fixes</li>
+          </ul>
+          <p>Best regards,<br>The Team</p>
+        </body>
+      </html>
+    HTML
+    text: <<~TEXT
+      Weekly Newsletter - #{Date.today}
+
+      Welcome to our weekly newsletter!
+
+      - Feature 1: New dashboard
+      - Feature 2: Improved performance
+      - Feature 3: Bug fixes
+
+      Best regards,
+      The Team
+    TEXT
+  )
+
+  puts "Email object created:"
+  puts "- From: #{email.from}"
+  puts "- To: #{email.to}"
+  puts "- Subject: #{email.subject}"
+  puts "- Has HTML: #{email.html?}"
+  puts "- Has Text: #{email.text?}"
+  puts "- Is Multipart: #{email.multipart?}"
+  puts "- Content Size: #{email.content_size} bytes"
+
+  # Send the email object
+  response = client.send_email(email)
+  puts "Email sent: #{response.success?}"
+rescue Poodle::ValidationError => e
+  puts "Validation failed: #{e.message}"
+  e.errors.each do |field, messages|
+    puts "  #{field}: #{messages.join(', ')}"
+  end
+end
+
+# Example 3: Environment variables
+puts "\n=== Example 3: Environment Variables ==="
+
+# Set environment variables
+ENV["POODLE_API_KEY"] = "your_api_key_here"
+ENV["POODLE_DEBUG"] = "true"
+ENV["POODLE_TIMEOUT"] = "45"
+
+# Create client using environment variables
+env_client = Poodle::Client.new
+puts "Client created using environment variables"
+puts "Debug mode: #{env_client.config.debug?}"
+puts "Timeout: #{env_client.config.timeout} seconds"
+
+# Example 4: Multiple content types
+puts "\n=== Example 4: Multiple Content Types ==="
+
+begin
+  # Send email with both HTML and text content
+  multipart_response = client.send(
+    from: "newsletter@example.com",
+    to: "subscriber@example.com",
+    subject: "Weekly Newsletter",
+    html: "<h1>Newsletter</h1><p>This week's updates...</p>",
+    text: "Newsletter\n\nThis week's updates..."
+  )
+
+  puts "Multipart email sent: #{multipart_response.success?}"
+rescue Poodle::Error => e
+  puts "Multipart email error: #{e.message}"
+end
+
+# Example 5: Comprehensive error handling
+puts "\n=== Example 5: Error Handling ==="
+
+def send_email_with_retry(client, email_data, max_retries: 3)
+  retries = 0
+
+  begin
+    response = client.send(email_data)
+    puts "Email sent successfully: #{response.message}"
+    response
+  rescue Poodle::RateLimitError => e
+    handle_rate_limit_error(e, retries, max_retries)
+    retries += 1
+    retry
+  rescue Poodle::NetworkError => e
+    handle_network_error(e, retries, max_retries)
+    retries += 1
+    retry
+  rescue Poodle::ServerError => e
+    handle_server_error(e, retries, max_retries)
+    retries += 1
+    retry
+  rescue Poodle::ValidationError => e
+    handle_validation_error(e)
+  rescue Poodle::AuthenticationError => e
+    handle_authentication_error(e)
+  rescue Poodle::PaymentError => e
+    handle_payment_error(e)
+  rescue Poodle::ForbiddenError => e
+    handle_forbidden_error(e)
+  end
+end
+
+def handle_rate_limit_error(error, retries, max_retries)
+  if retries < max_retries && error.retry_after
+    puts "Rate limited. Retrying in #{error.retry_after} seconds... (attempt #{retries + 1}/#{max_retries})"
+    sleep(error.retry_after)
+  else
+    puts "Rate limit exceeded. Max retries reached."
+    raise error
+  end
+end
+
+def handle_network_error(error, retries, max_retries)
+  if retries < max_retries
+    puts "Network error. Retrying... (attempt #{retries + 1}/#{max_retries})"
+    sleep(2**(retries + 1)) # Exponential backoff
+  else
+    puts "Network error. Max retries reached."
+    raise error
+  end
+end
+
+def handle_server_error(error, retries, max_retries)
+  if retries < max_retries
+    puts "Server error. Retrying... (attempt #{retries + 1}/#{max_retries})"
+    sleep(2**(retries + 1))
+  else
+    puts "Server error. Max retries reached."
+    raise error
+  end
+end
+
+def handle_validation_error(error)
+  puts "Validation error (not retryable): #{error.message}"
+  puts "Errors: #{error.errors}"
+  raise error
+end
+
+def handle_authentication_error(error)
+  puts "Authentication error (not retryable): #{error.message}"
+  raise error
+end
+
+def handle_payment_error(error)
+  puts "Payment required: #{error.message}"
+  puts "Upgrade URL: #{error.upgrade_url}" if error.upgrade_url
+  raise error
+end
+
+def handle_forbidden_error(error)
+  puts "Access forbidden: #{error.message}"
+  puts "Reason: #{error.reason}" if error.reason
+  raise error
+end
+
+# Test the retry mechanism
+email_data = {
+  from: "retry@example.com",
+  to: "test@example.com",
+  subject: "Retry Test",
+  html: "<p>Testing retry mechanism</p>"
+}
+
+begin
+  send_email_with_retry(client, email_data)
+rescue Poodle::Error => e
+  puts "Final error: #{e.message}"
+end
+
+# Example 6: Batch sending (conceptual)
+puts "\n=== Example 6: Batch Sending ==="
+
+recipients = [
+  "user1@example.com",
+  "user2@example.com",
+  "user3@example.com"
+]
+
+successful_sends = 0
+failed_sends = 0
+
+recipients.each_with_index do |recipient, index|
+  response = client.send(
+    from: "batch@example.com",
+    to: recipient,
+    subject: "Batch Email #{index + 1}",
+    html: "<p>Hello #{recipient}! This is batch email ##{index + 1}</p>"
+  )
+
+  if response.success?
+    successful_sends += 1
+    puts "✅ Sent to #{recipient}"
+  else
+    failed_sends += 1
+    puts "❌ Failed to send to #{recipient}: #{response.message}"
+  end
+
+  # Rate limiting: wait between sends
+  sleep(0.1)
+rescue Poodle::Error => e
+  failed_sends += 1
+  puts "❌ Error sending to #{recipient}: #{e.message}"
+end
+
+puts "\nBatch sending complete:"
+puts "Successful: #{successful_sends}"
+puts "Failed: #{failed_sends}"
+puts "Total: #{recipients.length}"
+
+# Clean up environment variables
+ENV.delete("POODLE_API_KEY")
+ENV.delete("POODLE_DEBUG")
+ENV.delete("POODLE_TIMEOUT")