kapso-client-ruby 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1396532c211130ca44e86a95c6928fed4e9005041326f64bf3bad63ef187eb9
-  data.tar.gz: 563208fa7bd2c5c4d1025e0f05ac400b52aaa2c42bad5c99279803d985eb4bd1
+  metadata.gz: 30d9beac96525aec644d8107458cf3cc409887d9ae53955ef8304fee43ca1e4e
+  data.tar.gz: 6979f6c7289e276439fc35aaf2b82d73f6bf2b7fc1be21fe50ca1f2e012a7217
 SHA512:
-  metadata.gz: c90eb6b79eb4a63e0c0c5bff5194b2ae0dbd9b1fb8ceff914b15053b8b3b2ad5a3fdcb85e54e197c241fc760aad7f75b0b841f765cca8e60ca229c574e4340c2
-  data.tar.gz: e1191ea0de205a6590e4f9affa69adf315a007fb0479b89a7a2d0507644f8ccbbdc34ad653be748b62b6c4a0cd1c91f835ec539e31f2bc25399dfccf29eed970
+  metadata.gz: f95bd5f312ed0b109da69b4213f0a1ff5c005765c4b71f9b764518f2c0d3fbf033add73a6e7144f856800838cdf3497cd81e85176645f0cf3df0b847c945b3bd
+  data.tar.gz: 547ef0b79fb3b2ef6fece9d851a78862ffee2b0ac22420d28b927bcb050527c9604788b66c831d10e2a9881d8ad9f4e5f841208f63cc9bc109a78d5cb9cd6a6c

data/CHANGELOG.md

@@ -9,8 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- Initial release of WhatsApp Cloud API Ruby SDK
-- Complete WhatsApp Cloud API support with all message types
+- Initial release of Kapso API Ruby SDK
+- Complete Kapso API support with all message types
 - Support for text, image, audio, video, document, sticker, location, and contact messages
 - Interactive message support (buttons, lists, product catalogs)
 - Template message creation and management

data/RAILS_INTEGRATION.md

@@ -0,0 +1,478 @@
+# Rails Integration Guide
+
+This guide shows you how to integrate KapsoClientRuby with your Rails application for sending WhatsApp messages through the Kapso API.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem 'kapso-client-ruby'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Setup with Generator
+
+The easiest way to set up KapsoClientRuby in your Rails app is using the built-in generator:
+
+```bash
+rails generate kapso_client_ruby:install
+```
+
+This will create:
+- `config/initializers/kapso_client_ruby.rb` - Configuration file
+- `app/controllers/kapso_webhooks_controller.rb` - Webhook handler
+- `app/services/kapso_message_service.rb` - Service class for messaging
+- `.env.example` - Environment variables template
+- Webhook routes in `config/routes.rb`
+
+## Manual Setup
+
+If you prefer to set up manually:
+
+### 1. Configuration
+
+Create `config/initializers/kapso_client_ruby.rb`:
+
+```ruby
+KapsoClientRuby.configure do |config|
+  config.api_key = ENV['KAPSO_API_KEY']
+  config.phone_number_id = ENV['KAPSO_PHONE_NUMBER_ID']
+  config.business_account_id = ENV['KAPSO_BUSINESS_ACCOUNT_ID']
+  
+  # Optional settings
+  config.debug = Rails.env.development?
+  config.logger = Rails.logger
+  config.timeout = 30
+end
+```
+
+### 2. Environment Variables
+
+Add to your `.env` file:
+
+```bash
+KAPSO_API_KEY=your_api_key_here
+KAPSO_PHONE_NUMBER_ID=your_phone_number_id_here
+KAPSO_BUSINESS_ACCOUNT_ID=your_business_account_id_here
+```
+
+### 3. Service Class
+
+Create `app/services/kapso_message_service.rb`:
+
+```ruby
+class KapsoMessageService
+  def initialize
+    @service = KapsoClientRuby::Rails::Service.new
+  end
+
+  def send_welcome_message(user)
+    @service.send_template_message(
+      to: user.phone_number,
+      template_name: 'welcome_message',
+      language: 'en',
+      components: [
+        {
+          type: 'body',
+          parameters: [
+            { type: 'text', text: user.first_name }
+          ]
+        }
+      ]
+    )
+  end
+end
+```
+
+## Usage Examples
+
+### Sending Messages in Controllers
+
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = User.new(user_params)
+    
+    if @user.save
+      # Send welcome message
+      KapsoMessageService.new.send_welcome_message(@user)
+      redirect_to @user, notice: 'User created and welcome message sent!'
+    else
+      render :new
+    end
+  end
+end
+```
+
+### Using in Models
+
+```ruby
+class Order < ApplicationRecord
+  belongs_to :user
+  
+  after_create :send_confirmation_message
+  
+  private
+  
+  def send_confirmation_message
+    return unless user.phone_number.present?
+    
+    KapsoMessageService.new.send_order_confirmation(self)
+  rescue KapsoClientRuby::Error => e
+    Rails.logger.error "Failed to send order confirmation: #{e.message}"
+  end
+end
+```
+
+### Background Jobs
+
+For better performance, send messages in background jobs:
+
+```ruby
+class SendWhatsAppMessageJob < ApplicationJob
+  queue_as :default
+  
+  def perform(phone_number, message_type, **options)
+    service = KapsoMessageService.new
+    
+    case message_type
+    when 'welcome'
+      service.send_welcome_message(options[:user])
+    when 'order_confirmation'
+      service.send_order_confirmation(options[:order])
+    end
+  end
+end
+
+# Usage in controller:
+SendWhatsAppMessageJob.perform_later(user.phone_number, 'welcome', user: user)
+```
+
+## Webhook Integration
+
+### 1. Webhook Controller
+
+The generated webhook controller handles incoming WhatsApp messages and status updates:
+
+```ruby
+class KapsoWebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def verify
+    # Webhook verification logic
+  end
+
+  def create
+    service = KapsoClientRuby::Rails::Service.new
+    service.process_webhook(params.to_unsafe_h)
+    render json: { status: 'ok' }
+  end
+end
+```
+
+### 2. Routes
+
+Add to `config/routes.rb`:
+
+```ruby
+post '/webhooks/kapso', to: 'kapso_webhooks#create'
+get '/webhooks/kapso', to: 'kapso_webhooks#verify'
+```
+
+### 3. Event Listeners
+
+Subscribe to WhatsApp events in your initializer:
+
+```ruby
+# In config/initializers/kapso_client_ruby.rb
+
+ActiveSupport::Notifications.subscribe('kapso.message_received') do |name, start, finish, id, payload|
+  message = payload[:message]
+  
+  # Handle incoming message
+  HandleIncomingMessageJob.perform_later(message)
+end
+
+ActiveSupport::Notifications.subscribe('kapso.message_status_updated') do |name, start, finish, id, payload|
+  status = payload[:status]
+  
+  # Update message status in database
+  UpdateMessageStatusJob.perform_later(status)
+end
+```
+
+## Available Rake Tasks
+
+```bash
+# Test configuration and send test message
+rails kapso:test
+
+# List available templates
+rails kapso:templates
+
+# Check message status
+rails kapso:message_status[message_id]
+
+# Validate webhook configuration
+rails kapso:validate_webhook
+
+# Generate sample .env file
+rails kapso:sample_env
+```
+
+## Configuration Options
+
+All configuration options available in the Rails initializer:
+
+```ruby
+KapsoClientRuby.configure do |config|
+  # Required
+  config.api_key = ENV['KAPSO_API_KEY']
+  config.phone_number_id = ENV['KAPSO_PHONE_NUMBER_ID']
+  config.business_account_id = ENV['KAPSO_BUSINESS_ACCOUNT_ID']
+  
+  # API Configuration
+  config.api_host = ENV.fetch('KAPSO_API_HOST', 'https://graph.facebook.com')
+  config.api_version = ENV.fetch('KAPSO_API_VERSION', 'v18.0')
+  config.timeout = ENV.fetch('KAPSO_TIMEOUT', 30).to_i
+  
+  # Logging and Debug
+  config.debug = Rails.env.development?
+  config.logger = Rails.logger
+  
+  # Retry Configuration
+  config.retry_on_failure = true
+  config.max_retries = 3
+end
+```
+
+## Rails-Specific Features
+
+### 1. ActiveSupport Notifications
+
+The gem automatically publishes events that you can subscribe to:
+
+- `kapso.message_received` - When a WhatsApp message is received
+- `kapso.message_status_updated` - When message delivery status changes
+- `kapso.template_status_updated` - When template approval status changes
+
+### 2. Rails Logger Integration
+
+All Kapso operations automatically log to Rails.logger with appropriate log levels.
+
+### 3. Environment-Based Configuration
+
+The gem respects Rails environments and can be configured differently for development, test, and production.
+
+### 4. Rails Service Pattern
+
+The `KapsoClientRuby::Rails::Service` class follows Rails service object patterns and integrates seamlessly with Rails applications.
+
+## Testing
+
+### RSpec Integration
+
+```ruby
+# spec/rails_helper.rb
+RSpec.configure do |config|
+  config.before(:each) do
+    # Mock Kapso API calls in tests
+    allow_any_instance_of(KapsoClientRuby::Client).to receive(:send_request)
+      .and_return({ 'messages' => [{ 'id' => 'test_message_id' }] })
+  end
+end
+
+# spec/services/kapso_message_service_spec.rb
+RSpec.describe KapsoMessageService do
+  let(:user) { create(:user, phone_number: '+1234567890') }
+  let(:service) { described_class.new }
+  
+  describe '#send_welcome_message' do
+    it 'sends a welcome message to the user' do
+      expect(service).to receive(:send_template_message)
+        .with(hash_including(to: user.phone_number))
+      
+      service.send_welcome_message(user)
+    end
+  end
+end
+```
+
+### Test Configuration
+
+```ruby
+# config/environments/test.rb
+config.kapso.debug = false
+config.kapso.logger = Logger.new('/dev/null') # Silence logs in tests
+```
+
+## Error Handling
+
+```ruby
+class KapsoMessageService
+  def send_message_with_retry(phone_number, message)
+    retries = 0
+    max_retries = 3
+    
+    begin
+      send_text_message(to: phone_number, text: message)
+    rescue KapsoClientRuby::RateLimitError => e
+      if retries < max_retries
+        retries += 1
+        sleep(2 ** retries) # Exponential backoff
+        retry
+      else
+        Rails.logger.error "Rate limit exceeded after #{max_retries} retries: #{e.message}"
+        raise
+      end
+    rescue KapsoClientRuby::Error => e
+      Rails.logger.error "Kapso API error: #{e.message}"
+      # Handle gracefully or re-raise depending on your needs
+      nil
+    end
+  end
+end
+```
+
+## Production Considerations
+
+### 1. Environment Variables
+
+Use Rails credentials or a secure environment variable management system:
+
+```bash
+# Using Rails credentials
+rails credentials:edit
+
+# Add:
+kapso:
+  api_key: your_actual_api_key
+  phone_number_id: your_phone_number_id
+  business_account_id: your_business_account_id
+```
+
+```ruby
+# In initializer
+config.api_key = Rails.application.credentials.dig(:kapso, :api_key)
+```
+
+### 2. Background Processing
+
+Always use background jobs for message sending in production:
+
+```ruby
+class User < ApplicationRecord
+  after_create :send_welcome_message_async
+  
+  private
+  
+  def send_welcome_message_async
+    SendWelcomeMessageJob.perform_later(self)
+  end
+end
+```
+
+### 3. Rate Limiting
+
+Implement rate limiting to avoid hitting API limits:
+
+```ruby
+class KapsoMessageService
+  include ActionController::Helpers
+  
+  def send_message(phone_number, message)
+    # Check rate limit before sending
+    cache_key = "kapso_rate_limit:#{phone_number}"
+    
+    if Rails.cache.read(cache_key).to_i >= 10 # 10 messages per hour
+      raise "Rate limit exceeded for #{phone_number}"
+    end
+    
+    result = @service.send_text_message(to: phone_number, text: message)
+    
+    # Increment counter
+    Rails.cache.increment(cache_key, 1, expires_in: 1.hour)
+    
+    result
+  end
+end
+```
+
+### 4. Monitoring and Alerting
+
+```ruby
+# In initializer, add error tracking
+ActiveSupport::Notifications.subscribe('kapso.error') do |name, start, finish, id, payload|
+  error = payload[:error]
+  
+  # Send to error tracking service
+  Bugsnag.notify(error) if defined?(Bugsnag)
+  Sentry.capture_exception(error) if defined?(Sentry)
+end
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Invalid Phone Number Format**
+   ```ruby
+   # Ensure phone numbers are in E.164 format
+   phone_number = "+1#{user.phone.gsub(/\D/, '')}"
+   ```
+
+2. **Missing Template Components**
+   ```ruby
+   # Always include required template parameters
+   components = [
+     {
+       type: 'body',
+       parameters: [
+         { type: 'text', text: user.name }
+       ]
+     }
+   ]
+   ```
+
+3. **Webhook Verification Failures**
+   ```ruby
+   # Make sure webhook verification token matches
+   verify_token = params['hub.verify_token']
+   expected_token = ENV['KAPSO_WEBHOOK_VERIFY_TOKEN']
+   ```
+
+### Debug Mode
+
+Enable debug mode in development:
+
+```ruby
+# config/environments/development.rb
+config.kapso.debug = true
+```
+
+This will log all API requests and responses to help with debugging.
+
+## Support
+
+For issues specific to Rails integration, please check:
+
+1. Rails logs for detailed error messages
+2. Kapso API documentation
+3. GitHub issues: https://github.com/PabloB07/kapso-client-ruby/issues
+
+## Contributing
+
+To contribute to Rails integration features:
+
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for Rails-specific functionality
+4. Submit a pull request
+
+The Rails integration code is located in `lib/kapso_client_ruby/rails/`.

data/README.md

@@ -1,4 +1,4 @@
-# WhatsApp Cloud API Ruby SDK
+# Kapso API Ruby SDK
 
 [![Gem Version](https://badge.fury.io/rb/whatsapp-cloud-api-ruby.svg)](https://badge.fury.io/rb/whatsapp-cloud-api-ruby)
 [![Ruby](https://img.shields.io/badge/ruby-%3E%3D%202.7.0-red.svg)](https://www.ruby-lang.org/)
@@ -8,7 +8,7 @@ A comprehensive Ruby client library for the [WhatsApp Business Cloud API](https:
 
 ## Features
 
-- 🚀 **Complete API Coverage**: All WhatsApp Cloud API endpoints supported
+- 🚀 **Complete API Coverage**: All Kapso Cloud API endpoints supported
 - 📱 **Rich Message Types**: Text, media, templates, interactive messages, and more
 - 🔐 **Dual Authentication**: Meta Graph API and Kapso Proxy support
 - 🛡️ **Smart Error Handling**: Comprehensive error categorization and retry logic
@@ -16,13 +16,14 @@ A comprehensive Ruby client library for the [WhatsApp Business Cloud API](https:
 - 🔍 **Debug Support**: Detailed logging and request/response tracing
 - 📚 **Type Safety**: Structured response objects and validation
 - ⚡ **Performance**: HTTP connection pooling and efficient request handling
+- 🛤️ **Rails Integration**: First-class Rails support with generators, service classes, and background jobs
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'whatsapp-cloud-api-ruby'
+gem 'kapso-client-api'
 ```
 
 And then execute:
@@ -34,18 +35,35 @@ $ bundle install
 Or install it yourself as:
 
 ```bash
-$ gem install whatsapp-cloud-api-ruby
+$ gem install kapso-client-api
 ```
 
+### Rails Integration
+
+For Rails applications, use the built-in generator to set up everything automatically:
+
+```bash
+rails generate kapso_client_ruby:install
+```
+
+This creates:
+- Configuration initializer
+- Webhook controller
+- Service class for messaging
+- Background job examples
+- Routes for webhooks
+
+See the [Rails Integration Guide](RAILS_INTEGRATION.md) for detailed Rails-specific documentation.
+
 ## Quick Start
 
 ### Basic Setup
 
 ```ruby
-require 'whatsapp_cloud_api'
+require 'kapso_client_api'
 
 # Initialize client with Meta Graph API access token
-client = WhatsAppCloudApi::Client.new(
+client = KapsoClientRuby::Client.new(
   access_token: 'your_access_token'
 )
 
@@ -63,7 +81,7 @@ puts "Message sent: #{response.messages.first.id}"
 
 ```ruby
 # Initialize client with Kapso API key for enhanced features
-kapso_client = WhatsAppCloudApi::Client.new(
+kapso_client = KapsoClientRuby::Client.new(
   kapso_api_key: 'your_kapso_api_key',
   base_url: 'https://app.kapso.ai/api/meta'
 )
@@ -359,7 +377,7 @@ Access enhanced features with Kapso proxy:
 
 ```ruby
 # Initialize Kapso client
-kapso_client = WhatsAppCloudApi::Client.new(
+kapso_client = KapsoClientRuby::Client.new(
   kapso_api_key: 'your_kapso_key',
   base_url: 'https://app.kapso.ai/api/meta'
 )
@@ -417,7 +435,7 @@ results = kapso_client.contacts.search(
 ### Global Configuration
 
 ```ruby
-WhatsAppCloudApi.configure do |config|
+KapsoClientRuby.configure do |config|
   config.debug = true
   config.timeout = 60
   config.open_timeout = 10
@@ -429,7 +447,7 @@ end
 ### Client Configuration
 
 ```ruby
-client = WhatsAppCloudApi::Client.new(
+client = KapsoClientRuby::Client.new(
   access_token: 'token',
   debug: true,
   timeout: 30,
@@ -443,7 +461,7 @@ Enable debug logging to see detailed HTTP requests and responses:
 
 ```ruby
 # Enable debug mode
-client = WhatsAppCloudApi::Client.new(
+client = KapsoClientRuby::Client.new(
   access_token: 'token',
   debug: true
 )
@@ -452,7 +470,7 @@ client = WhatsAppCloudApi::Client.new(
 logger = Logger.new(STDOUT)
 logger.level = Logger::DEBUG
 
-client = WhatsAppCloudApi::Client.new(
+client = KapsoClientRuby::Client.new(
   access_token: 'token',
   logger: logger
 )
@@ -469,7 +487,7 @@ begin
     to: 'invalid_number',
     body: 'Test'
   )
-rescue WhatsAppCloudApi::Errors::GraphApiError => e
+rescue KapsoClientRuby::Errors::GraphApiError => e
   puts "Error: #{e.message}"
   puts "Category: #{e.category}"
   puts "HTTP Status: #{e.http_status}"
@@ -538,7 +556,7 @@ def send_with_retry(client, max_retries = 3)
       to: '+1234567890',
       body: 'Test message'
     )
-  rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  rescue KapsoClientRuby::Errors::GraphApiError => e
     retries += 1
     
     case e.retry_hint[:action]
@@ -651,7 +669,7 @@ end
 # In your tests
 RSpec.describe 'Messages' do
   it 'sends text message', :vcr do
-    client = WhatsAppCloudApi::Client.new(access_token: 'test_token')
+    client = KapsoClientRuby::Client.new(access_token: 'test_token')
     
     response = client.messages.send_text(
       phone_number_id: 'test_phone_id',