laneful-ruby 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 92cd0ae4c28744530a747d496d4b22e65dc92e6f2238739b59e75f7dd36769a7
+  data.tar.gz: 87e2c139cb4e26e60c6209f87b88241a0e4161e19b1ffc2dd9da0f254654843c
+SHA512:
+  metadata.gz: f8218f49eb9b96cce7b4941fdfe058ef88017c356b0dedc8c18f7bd46cf0398a598255fcbe0a74737d695a0282f0a5e7660a229a94de7406e9694c07b0dcfa72
+  data.tar.gz: 61498ac2d546d3971e6054b5603dbb777dac4b14efb4ac946aa4ac90f89765ffc5d347192b7d5200800ef4dfda2af033d91b1c58d6cdd3704bac9f9c208a199a

data/.rubocop.yml

@@ -0,0 +1,31 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+
+# Disable some strict rules for test files and gemspec
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/MethodLength:
+  Max: 30
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/AbcSize:
+  Max: 80
+
+Metrics/CyclomaticComplexity:
+  Max: 40
+
+Metrics/PerceivedComplexity:
+  Max: 40
+
+Metrics/ParameterLists:
+  Max: 5
+
+Layout/LineLength:
+  Max: 120

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Laneful
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/Makefile

@@ -0,0 +1,49 @@
+# Laneful Ruby SDK Makefile
+
+.PHONY: help test lint build publish clean install setup
+
+# Default target
+help:
+	@echo "Available commands:"
+	@echo "  setup    - Install dependencies"
+	@echo "  test     - Run tests"
+	@echo "  lint     - Run code linting"
+	@echo "  build    - Build the gem"
+	@echo "  publish  - Publish to RubyGems (requires RUBYGEMS_API_KEY)"
+	@echo "  install  - Install gem locally"
+	@echo "  clean    - Clean up built gems"
+
+# Install dependencies
+setup:
+	bundle install
+
+# Run tests
+test:
+	bundle exec rspec
+
+# Run linting
+lint:
+	bundle exec rubocop
+
+# Build gem
+build:
+	gem build laneful-ruby.gemspec
+
+# Publish to RubyGems
+publish:
+	@if [ -z "$$GEM_HOST_API_KEY" ]; then \
+		echo "Error: GEM_HOST_API_KEY environment variable is not set"; \
+		echo "Please set your RubyGems API key: export GEM_HOST_API_KEY=your_api_key_here"; \
+		exit 1; \
+	fi
+	./scripts/publish.sh
+
+# Install gem locally
+install:
+	gem build laneful-ruby.gemspec
+	gem install laneful-ruby-*.gem
+
+# Clean up
+clean:
+	rm -f laneful-ruby-*.gem
+

data/README.md

@@ -0,0 +1,456 @@
+# Laneful Ruby SDK
+
+A modern Ruby client library for the Laneful email API with support for sending emails, templates, tracking, and webhooks.
+
+## Requirements
+
+- Ruby 3.0 or higher
+- Bundler (for dependency management)
+
+## Installation
+
+### Using Bundler
+
+Add the following to your `Gemfile`:
+
+```ruby
+gem 'laneful-ruby'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+### Manual Installation
+
+```bash
+git clone https://github.com/lanefulhq/laneful-ruby.git
+cd laneful-ruby
+bundle install
+bundle exec rake install
+```
+
+## Quick Start
+
+```ruby
+require 'laneful'
+
+# Create client
+client = Laneful::Client.new(
+  'https://your-endpoint.send.laneful.net',
+  'your-auth-token'
+)
+
+# Create email
+email = Laneful::Email::Builder.new
+  .from(Laneful::Address.new('sender@example.com', 'Your Name'))
+  .to(Laneful::Address.new('recipient@example.com', 'Recipient Name'))
+  .subject('Hello from Laneful Ruby SDK!')
+  .text_content('This is a simple test email.')
+  .build
+
+# Send email
+response = client.send_email(email)
+puts "Email sent successfully!"
+```
+
+## Features
+
+- Send single or multiple emails
+- Plain text and HTML content
+- Email templates with dynamic data
+- File attachments
+- Email tracking (opens, clicks, unsubscribes)
+- Custom headers and reply-to addresses
+- Scheduled sending
+- Webhook signature verification
+- Comprehensive error handling
+- Modern Ruby 3.0+ features
+
+## Examples
+
+### Simple Text Email
+
+```ruby
+email = Laneful::Email::Builder.new
+  .from(Laneful::Address.new('sender@example.com'))
+  .to(Laneful::Address.new('user@example.com'))
+  .subject('Simple Email')
+  .text_content('This is a simple text email.')
+  .build
+
+response = client.send_email(email)
+```
+
+### HTML Email with Tracking
+
+```ruby
+tracking = Laneful::TrackingSettings.new(opens: true, clicks: true, unsubscribes: false)
+
+email = Laneful::Email::Builder.new
+  .from(Laneful::Address.new('sender@example.com'))
+  .to(Laneful::Address.new('user@example.com'))
+  .subject('HTML Email with Tracking')
+  .html_content('<h1>Welcome!</h1><p>This is an <strong>HTML email</strong> with tracking enabled.</p>')
+  .text_content('Welcome! This is an HTML email with tracking enabled.')
+  .tracking(tracking)
+  .build
+
+response = client.send_email(email)
+```
+
+### Template Email
+
+```ruby
+email = Laneful::Email::Builder.new
+  .from(Laneful::Address.new('sender@example.com'))
+  .to(Laneful::Address.new('user@example.com'))
+  .template_id('welcome-template')
+  .template_data({
+    'name' => 'John Doe',
+    'company' => 'Acme Corp'
+  })
+  .build
+
+response = client.send_email(email)
+```
+
+### Email with Attachments
+
+```ruby
+# Create attachment from file
+attachment = Laneful::Attachment.from_file('/path/to/document.pdf')
+
+email = Laneful::Email::Builder.new
+  .from(Laneful::Address.new('sender@example.com'))
+  .to(Laneful::Address.new('user@example.com'))
+  .subject('Document Attached')
+  .text_content('Please find the document attached.')
+  .attachment(attachment)
+  .build
+
+response = client.send_email(email)
+```
+
+### Multiple Recipients
+
+```ruby
+email = Laneful::Email::Builder.new
+  .from(Laneful::Address.new('sender@example.com'))
+  .to(Laneful::Address.new('user1@example.com'))
+  .to(Laneful::Address.new('user2@example.com', 'User Two'))
+  .cc(Laneful::Address.new('cc@example.com'))
+  .bcc(Laneful::Address.new('bcc@example.com'))
+  .subject('Multiple Recipients')
+  .text_content('This email has multiple recipients.')
+  .build
+
+response = client.send_email(email)
+```
+
+### Scheduled Email
+
+```ruby
+# Schedule for 24 hours from now
+send_time = Time.now.to_i + (24 * 60 * 60)
+
+email = Laneful::Email::Builder.new
+  .from(Laneful::Address.new('sender@example.com'))
+  .to(Laneful::Address.new('user@example.com'))
+  .subject('Scheduled Email')
+  .text_content('This email was scheduled.')
+  .send_time(send_time)
+  .build
+
+response = client.send_email(email)
+```
+
+### Multiple Emails
+
+```ruby
+emails = [
+  Laneful::Email::Builder.new
+    .from(Laneful::Address.new('sender@example.com'))
+    .to(Laneful::Address.new('user1@example.com'))
+    .subject('Email 1')
+    .text_content('First email content.')
+    .build,
+  Laneful::Email::Builder.new
+    .from(Laneful::Address.new('sender@example.com'))
+    .to(Laneful::Address.new('user2@example.com'))
+    .subject('Email 2')
+    .text_content('Second email content.')
+    .build
+]
+
+response = client.send_emails(emails)
+```
+
+### Custom Timeout
+
+```ruby
+client = Laneful::Client.new(
+  'https://your-endpoint.send.laneful.net',
+  'your-auth-token',
+  timeout: 60  # 60 second timeout
+)
+```
+
+## Webhook Verification
+
+```ruby
+# In your webhook handler
+payload = request.body.read
+signature = request.headers['X-Laneful-Signature']
+secret = 'your-webhook-secret'
+
+if Laneful::WebhookVerifier.verify_signature(secret, payload, signature)
+  # Process webhook data
+  data = JSON.parse(payload)
+  # Handle webhook event
+else
+  # Invalid signature
+  head :unauthorized
+end
+```
+
+## Error Handling
+
+```ruby
+begin
+  response = client.send_email(email)
+  puts "Email sent successfully"
+rescue Laneful::ValidationException => e
+  puts "Validation error: #{e.message}"
+rescue Laneful::ApiException => e
+  puts "API error: #{e.message}"
+  puts "Status code: #{e.status_code}"
+  puts "Error message: #{e.error_message}"
+rescue Laneful::HttpException => e
+  puts "HTTP error: #{e.message}"
+  puts "Status code: #{e.status_code}"
+rescue StandardError => e
+  puts "Unexpected error: #{e.message}"
+end
+```
+
+## API Reference
+
+### Laneful::Client
+
+#### Constructor
+
+```ruby
+Laneful::Client.new(base_url, auth_token, timeout: 30)
+```
+
+- `base_url` - The base URL of the Laneful API
+- `auth_token` - The authentication token
+- `timeout` - Request timeout in seconds (optional, default: 30)
+
+#### Methods
+
+- `send_email(email)` - Sends a single email
+- `send_emails(emails)` - Sends multiple emails
+
+### Laneful::Email::Builder
+
+#### Required Fields
+
+- `from(address)` - Sender address
+
+#### Optional Fields
+
+- `to(address)` - Recipient addresses
+- `cc(address)` - CC addresses
+- `bcc(address)` - BCC addresses
+- `subject(subject)` - Email subject
+- `text_content(content)` - Plain text content
+- `html_content(content)` - HTML content
+- `template_id(id)` - Template ID
+- `template_data(data)` - Template data
+- `attachment(attachment)` - File attachments
+- `headers(headers)` - Custom headers
+- `reply_to(address)` - Reply-to address
+- `send_time(time)` - Scheduled send time (Unix timestamp)
+- `webhook_data(data)` - Webhook data
+- `tag(tag)` - Email tag
+- `tracking(tracking)` - Tracking settings
+
+### Laneful::Address
+
+```ruby
+Laneful::Address.new(email, name = nil)
+```
+
+- `email` - The email address (required)
+- `name` - The display name (optional)
+
+### Laneful::Attachment
+
+```ruby
+# From file
+Laneful::Attachment.from_file(file_path)
+
+# From raw data
+Laneful::Attachment.new(filename, content_type, content)
+```
+
+### Laneful::TrackingSettings
+
+```ruby
+Laneful::TrackingSettings.new(opens: false, clicks: false, unsubscribes: false)
+```
+
+### Laneful::WebhookVerifier
+
+```ruby
+Laneful::WebhookVerifier.verify_signature(secret, payload, signature)
+```
+
+## Exception Types
+
+- `Laneful::ValidationException` - Thrown when input validation fails
+- `Laneful::ApiException` - Thrown when the API returns an error response
+- `Laneful::HttpException` - Thrown when HTTP communication fails
+- `Laneful::LanefulException` - Base exception class for all SDK exceptions
+
+## Development
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
+
+### Code Quality
+
+```bash
+bundle exec rubocop
+```
+
+### Documentation
+
+```bash
+bundle exec yard doc
+```
+
+## Publishing to RubyGems
+
+This SDK can be published to RubyGems using a simple, automated workflow.
+
+### Prerequisites
+
+1. **Ruby 3.0+**: Ensure you have Ruby 3.0 or higher installed
+2. **Bundler**: Install bundler if not already installed (`gem install bundler`)
+3. **RubyGems API Key**: Get your API key from [RubyGems.org](https://rubygems.org/settings/edit)
+
+### Setting up your API Key
+
+```bash
+export GEM_HOST_API_KEY=your_api_key_here
+```
+
+### Publishing Methods
+
+#### Method 1: Using the Automated Script (Recommended)
+
+```bash
+./scripts/publish.sh
+```
+
+This script will:
+
+- Check Ruby version compatibility
+- Install dependencies
+- Run all tests
+- Perform code linting
+- Build the gem
+- Publish to RubyGems
+- Clean up built gem files
+
+#### Method 2: Using Make Commands
+
+**Install dependencies:**
+
+```bash
+make setup
+```
+
+**Run tests:**
+
+```bash
+make test
+```
+
+**Run linting:**
+
+```bash
+make lint
+```
+
+**Build the gem:**
+
+```bash
+make build
+```
+
+**Publish to RubyGems:**
+
+```bash
+make publish
+```
+
+#### Method 3: Manual Publishing
+
+**Install dependencies:**
+
+```bash
+bundle install
+```
+
+**Run tests:**
+
+```bash
+bundle exec rspec
+```
+
+**Run linting:**
+
+```bash
+bundle exec rubocop
+```
+
+**Build the gem:**
+
+```bash
+gem build laneful-ruby.gemspec
+```
+
+**Publish to RubyGems:**
+
+```bash
+gem push laneful-ruby-*.gem
+```
+
+### Version Management
+
+Before publishing, make sure to update the version in `lib/laneful/version.rb`:
+
+```ruby
+module Laneful
+  VERSION = "1.0.1".freeze  # Update this version
+end
+```
+
+Follow [Semantic Versioning](https://semver.org/) guidelines:
+
+- **MAJOR** version for incompatible API changes
+- **MINOR** version for backwards-compatible functionality additions
+- **PATCH** version for backwards-compatible bug fixes
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gem 'laneful-ruby'

data/examples/README.md

@@ -0,0 +1,53 @@
+# Laneful Ruby SDK Examples
+
+This directory contains example code demonstrating how to use the Laneful Ruby SDK.
+
+## Quick Start
+
+1. **Install the gem:**
+   ```bash
+   gem install laneful-ruby
+   ```
+
+2. **Or use Bundler:**
+   ```bash
+   cd examples
+   bundle install
+   ```
+
+3. **Configure the example:**
+   Edit `simple_example.rb` and replace the placeholder values:
+   - `base_url`: Your Laneful endpoint URL
+   - `auth_token`: Your authentication token
+   - Email addresses: Replace with your actual email addresses
+
+4. **Run the example:**
+   ```bash
+   ruby simple_example.rb
+   ```
+
+## Example Files
+
+- **`simple_example.rb`**: Demonstrates basic email sending functionality including:
+  - Simple text email
+  - HTML email with tracking
+  - Email with CC recipients
+  - Error handling
+
+## Configuration
+
+Before running the examples, make sure to:
+
+1. **Get your credentials** from your Laneful dashboard
+2. **Update the configuration** in the example files:
+   ```ruby
+   base_url = 'https://your-endpoint.send.laneful.net'
+   auth_token = 'your-auth-token'
+   ```
+3. **Use valid email addresses** for testing
+
+## More Examples
+
+For more comprehensive examples and API documentation, visit:
+- [Laneful Ruby SDK Documentation](https://docs.laneful.com/ruby)
+- [GitHub Repository](https://github.com/laneful/laneful-ruby)