laneful-ruby 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92cd0ae4c28744530a747d496d4b22e65dc92e6f2238739b59e75f7dd36769a7
-  data.tar.gz: 87e2c139cb4e26e60c6209f87b88241a0e4161e19b1ffc2dd9da0f254654843c
+  metadata.gz: 3b7c5f86e1e341b49312a27486067c2427323569459dba65f8fb2b247629a1fb
+  data.tar.gz: 649ca87028b16f0ede2b1e063390fe13043e12401e70e4637d6c69922d7b415e
 SHA512:
-  metadata.gz: f8218f49eb9b96cce7b4941fdfe058ef88017c356b0dedc8c18f7bd46cf0398a598255fcbe0a74737d695a0282f0a5e7660a229a94de7406e9694c07b0dcfa72
-  data.tar.gz: 61498ac2d546d3971e6054b5603dbb777dac4b14efb4ac946aa4ac90f89765ffc5d347192b7d5200800ef4dfda2af033d91b1c58d6cdd3704bac9f9c208a199a
+  metadata.gz: 1d0b108965868436f5b4cbdc6208891bfa51b877a3ec7b70cc4bf13745b793aeb8676d284e010e446acd27de221637c38e005d8399dde5a60adfaf3bf2ae9749
+  data.tar.gz: a50c27e76b6f4b47a8cc6ecee7e5b863bc6f3106127ba9e22e9e822e3b803c809c42202e78412b4b2afe5ab5afcafcbcb2f10c16d78dc923f57e453ca8b14c6b

data/README.md

@@ -203,7 +203,7 @@ client = Laneful::Client.new(
 ```ruby
 # In your webhook handler
 payload = request.body.read
-signature = request.headers['X-Laneful-Signature']
+signature = request.headers['x-webhook-signature']
 secret = 'your-webhook-secret'
 
 if Laneful::WebhookVerifier.verify_signature(secret, payload, signature)
@@ -337,120 +337,7 @@ bundle exec rubocop
 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/examples/simple_example.rb

@@ -8,8 +8,8 @@ puts '📧 Laneful Ruby SDK - Simple Example'
 puts "====================================\n"
 
 # Configuration - Replace with your actual credentials
-base_url = 'https://your-endpoint.send.laneful.net'
-auth_token = 'your-auth-token'
+base_url = 'https://your-subdomain.z1.send.dev.laneful.net'
+auth_token = 'priv-YourAuthTokenHere'
 
 # Email addresses - Replace with your actual addresses
 sender_email = 'sender@yourdomain.com'
@@ -50,6 +50,7 @@ rescue Laneful::ValidationException => e
   puts "❌ Validation error: #{e.message}"
 rescue Laneful::ApiException => e
   puts "❌ API error: #{e.message} (Status: #{e.status_code})"
+  puts "   Details: #{e.error_message}" if e.error_message
 rescue Laneful::HttpException => e
   puts "❌ HTTP error: #{e.message} (Status: #{e.status_code})"
 end
@@ -108,6 +109,7 @@ rescue Laneful::ValidationException => e
   puts "❌ Validation error: #{e.message}"
 rescue Laneful::ApiException => e
   puts "❌ API error: #{e.message} (Status: #{e.status_code})"
+  puts "   Details: #{e.error_message}" if e.error_message
 rescue Laneful::HttpException => e
   puts "❌ HTTP error: #{e.message} (Status: #{e.status_code})"
 end

data/lib/laneful/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Laneful
-  VERSION = '1.0.1'
+  VERSION = '1.1.0'
 end

data/lib/laneful/webhooks.rb

@@ -1,31 +1,116 @@
 # frozen_string_literal: true
 
+require 'json'
+require 'openssl'
+
 module Laneful
-  # Utility class for verifying webhook signatures
+  # Utility class for verifying webhook signatures and processing webhook payloads
   class WebhookVerifier
     ALGORITHM = 'sha256'
+    SIGNATURE_PREFIX = 'sha256='
+    SIGNATURE_HEADER_NAME = 'x-webhook-signature'
+
+    # Valid event types as documented
+    VALID_EVENT_TYPES = %w[
+      delivery open click drop spam_complaint unsubscribe bounce
+    ].freeze
 
-    # Verifies a webhook signature
+    # UUID pattern for lane_id validation
+    UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+    # Verifies a webhook signature with support for sha256= prefix
+    # @param secret [String] The webhook secret
+    # @param payload [String] The webhook payload
+    # @param signature [String] The signature to verify (may include 'sha256=' prefix)
+    # @return [Boolean] true if the signature is valid, false otherwise
     def self.verify_signature(secret, payload, signature)
       return false if secret.nil? || secret.strip.empty?
       return false if payload.nil?
       return false if signature.nil? || signature.strip.empty?
 
+      # Handle sha256= prefix as documented
+      clean_signature = if signature.start_with?(SIGNATURE_PREFIX)
+                          signature[SIGNATURE_PREFIX.length..]
+                        else
+                          signature
+                        end
+
       expected_signature = generate_signature(secret, payload)
-      secure_compare?(expected_signature, signature)
+      secure_compare?(expected_signature, clean_signature)
     rescue StandardError
       false
     end
 
     # Generates a signature for the given payload
-    def self.generate_signature(secret, payload)
+    # @param secret [String] The webhook secret
+    # @param payload [String] The payload to sign
+    # @param include_prefix [Boolean] Whether to include the 'sha256=' prefix
+    # @return [String] The generated signature
+    def self.generate_signature(secret, payload, include_prefix: false)
       digest = OpenSSL::Digest.new(ALGORITHM)
       hmac = OpenSSL::HMAC.new(secret, digest)
       hmac.update(payload)
-      hmac.hexdigest
+      signature = hmac.hexdigest
+      include_prefix ? "#{SIGNATURE_PREFIX}#{signature}" : signature
+    end
+
+    # Parse and validate webhook payload structure
+    # @param payload [String] The raw webhook payload JSON
+    # @return [Hash] Hash containing :is_batch boolean and :events array
+    # @raise [ArgumentError] If payload is invalid JSON or structure
+    def self.parse_webhook_payload(payload)
+      raise ArgumentError, 'Payload cannot be empty' if payload.nil? || payload.strip.empty?
+
+      data = JSON.parse(payload)
+
+      if data.is_a?(Array)
+        # Batch mode: array of events
+        events = data.map { |event| validate_and_parse_event(event) }
+        { is_batch: true, events: events }
+      elsif data.is_a?(Hash) && data.key?('event')
+        # Single event mode
+        event = validate_and_parse_event(data)
+        { is_batch: false, events: [event] }
+      else
+        raise ArgumentError, 'Invalid webhook payload structure'
+      end
+    rescue JSON::ParserError => e
+      raise ArgumentError, "Invalid JSON payload: #{e.message}"
+    end
+
+    # Get the webhook header name as documented
+    # @return [String] The correct header name for webhook signatures
+    def self.signature_header_name
+      SIGNATURE_HEADER_NAME
+    end
+
+    # Extract webhook signature from HTTP headers (supports multiple formats)
+    # @param headers [Hash] HTTP headers hash
+    # @return [String, nil] The webhook signature or nil if not found
+    def self.extract_signature_from_headers(headers)
+      return nil if headers.nil?
+
+      # Try documented header name first
+      signature = headers[SIGNATURE_HEADER_NAME]
+      return signature if signature
+
+      # Try uppercase version
+      upper_header = SIGNATURE_HEADER_NAME.upcase.tr('-', '_')
+      signature = headers[upper_header]
+      return signature if signature
+
+      # Try with HTTP_ prefix (common in Rack environments)
+      server_header = "HTTP_#{upper_header}"
+      signature = headers[server_header]
+      return signature if signature
+
+      nil
     end
 
     # Compares two strings in constant time to prevent timing attacks
+    # @param str_a [String] First string
+    # @param str_b [String] Second string
+    # @return [Boolean] true if strings are equal, false otherwise
     def self.secure_compare?(str_a, str_b)
       return false unless str_a.bytesize == str_b.bytesize
 
@@ -34,5 +119,49 @@ module Laneful
       str_b.each_byte { |byte| res |= byte ^ l.shift }
       res.zero?
     end
+
+    # Validate individual event structure according to documentation
+    # @param event [Hash] The event data
+    # @return [Hash] Parsed event hash
+    # @raise [ArgumentError] If event structure is invalid
+    def self.validate_and_parse_event(event)
+      raise ArgumentError, 'Event must be a hash' unless event.is_a?(Hash)
+
+      # Required fields
+      required_fields = %w[event email lane_id message_id timestamp]
+      required_fields.each do |field|
+        raise ArgumentError, "Missing required field: #{field}" unless event.key?(field)
+      end
+
+      # Validate event type
+      event_type = event['event']
+      raise ArgumentError, "Invalid event type: #{event_type}" unless VALID_EVENT_TYPES.include?(event_type)
+
+      # Validate email format
+      email = event['email']
+      raise ArgumentError, "Invalid email format: #{email}" unless valid_email?(email)
+
+      # Validate timestamp is numeric
+      timestamp = event['timestamp']
+      begin
+        Integer(timestamp)
+      rescue ArgumentError, TypeError
+        raise ArgumentError, 'Invalid timestamp format'
+      end
+
+      # Validate lane_id is a valid UUID format
+      lane_id = event['lane_id']
+      raise ArgumentError, "Invalid lane_id format: #{lane_id}" unless UUID_PATTERN.match?(lane_id)
+
+      # Return event with all fields (required + optional)
+      event
+    end
+
+    # Simple email validation
+    # @param email [String] The email to validate
+    # @return [Boolean] true if email format is valid
+    def self.valid_email?(email)
+      email.is_a?(String) && email.include?('@') && email.include?('.')
+    end
   end
 end

data/lib/laneful.rb

@@ -23,5 +23,5 @@ module Laneful
   DEFAULT_TIMEOUT = 30
 
   # User agent string
-  USER_AGENT = 'laneful-ruby/1.0.0'
+  USER_AGENT = 'laneful-ruby/1.0.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: laneful-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Laneful Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-05 00:00:00.000000000 Z
+date: 2025-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -52,7 +52,6 @@ files:
 - README.md
 - Rakefile
 - examples/Gemfile
-- examples/README.md
 - examples/simple_example.rb
 - laneful-ruby.gemspec
 - lib/laneful.rb

data/examples/README.md

@@ -1,53 +0,0 @@
-# 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)