kapso-client-ruby 1.0.0 → 1.0.1

data/lib/kapso_client_ruby/rails/railtie.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'rails/railtie'
+
+module KapsoClientRuby
+  module Rails
+    # Rails integration for KapsoClientRuby
+    class Railtie < ::Rails::Railtie
+      railtie_name :kapso_client_ruby
+
+      # Add kapso configuration to Rails application config
+      config.kapso = ActiveSupport::OrderedOptions.new
+
+      # Set default configuration values
+      config.before_configuration do |app|
+        app.config.kapso.api_key = nil
+        app.config.kapso.phone_number_id = nil
+        app.config.kapso.business_account_id = nil
+        app.config.kapso.api_host = 'https://graph.facebook.com'
+        app.config.kapso.api_version = 'v23.0'
+        app.config.kapso.timeout = 30
+        app.config.kapso.debug = false
+        app.config.kapso.logger = nil
+        app.config.kapso.retry_on_failure = true
+        app.config.kapso.max_retries = 3
+      end
+
+      # Initialize Kapso client after Rails application initialization
+      initializer 'kapso_client_ruby.configure' do |app|
+        KapsoClientRuby.configure do |config|
+          config.api_key = app.config.kapso.api_key || ENV['KAPSO_API_KEY']
+          config.phone_number_id = app.config.kapso.phone_number_id || ENV['KAPSO_PHONE_NUMBER_ID']
+          config.business_account_id = app.config.kapso.business_account_id || ENV['KAPSO_BUSINESS_ACCOUNT_ID']
+          config.api_host = app.config.kapso.api_host || ENV.fetch('KAPSO_API_HOST', 'https://graph.facebook.com')
+          config.api_version = app.config.kapso.api_version || ENV.fetch('KAPSO_API_VERSION', 'v23.0')
+          config.timeout = app.config.kapso.timeout || ENV.fetch('KAPSO_TIMEOUT', 30).to_i
+          config.debug = app.config.kapso.debug || ENV.fetch('KAPSO_DEBUG', 'false') == 'true'
+          config.logger = app.config.kapso.logger || ::Rails.logger
+          config.retry_on_failure = app.config.kapso.retry_on_failure
+          config.max_retries = app.config.kapso.max_retries || ENV.fetch('KAPSO_MAX_RETRIES', 3).to_i
+        end
+      end
+
+      # Add rake tasks
+      rake_tasks do
+        load 'kapso_client_ruby/rails/tasks.rake'
+      end
+
+      # Add generators
+      generators do
+        require 'kapso_client_ruby/rails/generators/install_generator'
+      end
+    end
+  end
+end

data/lib/kapso_client_ruby/rails/service.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+module KapsoClientRuby
+  module Rails
+    # Service class for Rails integration with KapsoClientRuby
+    # Provides a convenient interface for Rails applications to interact with the Kapso API
+    class Service
+      include ActiveSupport::Configurable
+
+      # @return [KapsoClientRuby::Client] The configured Kapso client
+      attr_reader :client
+
+      def initialize(client = nil)
+        @client = client || KapsoClientRuby::Client.new
+      end
+
+      # Send a text message
+      # @param to [String] The recipient's phone number
+      # @param text [String] The message text
+      # @param options [Hash] Additional options
+      # @return [Hash] API response
+      def send_text_message(to:, text:, **options)
+        Rails.logger.info "Sending text message to #{to}: #{text.truncate(50)}"
+        
+        result = client.messages.send_text(
+          to: to,
+          text: text,
+          **options
+        )
+        
+        Rails.logger.info "Message sent successfully. ID: #{result.dig('messages', 0, 'id')}"
+        result
+      rescue KapsoClientRuby::Error => e
+        Rails.logger.error "Failed to send text message: #{e.message}"
+        raise
+      end
+
+      # Send a template message
+      # @param to [String] The recipient's phone number
+      # @param template_name [String] The template name
+      # @param language [String] The language code (default: 'en')
+      # @param components [Array] Template components
+      # @return [Hash] API response
+      def send_template_message(to:, template_name:, language: 'en', components: [])
+        Rails.logger.info "Sending template message '#{template_name}' to #{to}"
+        
+        result = client.messages.send_template(
+          to: to,
+          name: template_name,
+          language: language,
+          components: components
+        )
+        
+        Rails.logger.info "Template message sent successfully. ID: #{result.dig('messages', 0, 'id')}"
+        result
+      rescue KapsoClientRuby::Error => e
+        Rails.logger.error "Failed to send template message: #{e.message}"
+        raise
+      end
+
+      # Send a media message
+      # @param to [String] The recipient's phone number
+      # @param media_type [String] Type of media ('image', 'document', 'video', 'audio')
+      # @param media_url [String] URL of the media file
+      # @param options [Hash] Additional options
+      # @return [Hash] API response
+      def send_media_message(to:, media_type:, media_url:, **options)
+        Rails.logger.info "Sending #{media_type} message to #{to}: #{media_url}"
+        
+        result = client.messages.send_media(
+          to: to,
+          type: media_type,
+          media_url: media_url,
+          **options
+        )
+        
+        Rails.logger.info "Media message sent successfully. ID: #{result.dig('messages', 0, 'id')}"
+        result
+      rescue KapsoClientRuby::Error => e
+        Rails.logger.error "Failed to send media message: #{e.message}"
+        raise
+      end
+
+      # Upload media file
+      # @param file_path [String] Path to the media file
+      # @param media_type [String] Type of media
+      # @return [Hash] Upload response with media ID
+      def upload_media(file_path:, media_type:)
+        Rails.logger.info "Uploading media file: #{file_path}"
+        
+        result = client.media.upload(
+          file_path: file_path,
+          type: media_type
+        )
+        
+        Rails.logger.info "Media uploaded successfully. ID: #{result['id']}"
+        result
+      rescue KapsoClientRuby::Error => e
+        Rails.logger.error "Failed to upload media: #{e.message}"
+        raise
+      end
+
+      # Get message status
+      # @param message_id [String] The message ID
+      # @return [Hash] Message status
+      def get_message_status(message_id)
+        Rails.logger.debug "Getting status for message: #{message_id}"
+        
+        result = client.messages.get_status(message_id)
+        
+        Rails.logger.debug "Message status: #{result['status']}"
+        result
+      rescue KapsoClientRuby::Error => e
+        Rails.logger.error "Failed to get message status: #{e.message}"
+        raise
+      end
+
+      # Get templates
+      # @param options [Hash] Query options
+      # @return [Array] List of templates
+      def get_templates(**options)
+        Rails.logger.debug "Fetching templates with options: #{options}"
+        
+        result = client.templates.list(**options)
+        
+        Rails.logger.debug "Found #{result['data']&.length || 0} templates"
+        result
+      rescue KapsoClientRuby::Error => e
+        Rails.logger.error "Failed to fetch templates: #{e.message}"
+        raise
+      end
+
+      # Process incoming webhook
+      # @param webhook_data [Hash] The webhook payload
+      # @return [Hash] Processed webhook data
+      def process_webhook(webhook_data)
+        Rails.logger.info "Processing webhook: #{webhook_data}"
+        
+        # Process webhook data based on type
+        entries = webhook_data['entry'] || []
+        
+        entries.each do |entry|
+          changes = entry['changes'] || []
+          
+          changes.each do |change|
+            case change['field']
+            when 'messages'
+              process_message_webhook(change['value'])
+            when 'message_template_status_update'
+              process_template_status_webhook(change['value'])
+            else
+              Rails.logger.warn "Unknown webhook field: #{change['field']}"
+            end
+          end
+        end
+        
+        { status: 'processed' }
+      rescue => e
+        Rails.logger.error "Failed to process webhook: #{e.message}"
+        raise
+      end
+
+      private
+
+      def process_message_webhook(value)
+        messages = value['messages'] || []
+        statuses = value['statuses'] || []
+        
+        messages.each do |message|
+          Rails.logger.info "Received message: #{message['id']} from #{message['from']}"
+          # Trigger Rails callback or event
+          ActiveSupport::Notifications.instrument('kapso.message_received', message: message)
+        end
+        
+        statuses.each do |status|
+          Rails.logger.info "Message status update: #{status['id']} -> #{status['status']}"
+          # Trigger Rails callback or event
+          ActiveSupport::Notifications.instrument('kapso.message_status_updated', status: status)
+        end
+      end
+
+      def process_template_status_webhook(value)
+        Rails.logger.info "Template status update: #{value}"
+        # Trigger Rails callback or event
+        ActiveSupport::Notifications.instrument('kapso.template_status_updated', template_status: value)
+      end
+    end
+  end
+end

data/lib/kapso_client_ruby/rails/tasks.rake

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+namespace :kapso do
+  desc 'Test Kapso configuration and send a test message'
+  task test: :environment do
+    puts "🔧 Testing Kapso configuration..."
+    
+    # Check configuration
+    client = KapsoClientRuby::Client.new
+    puts "✅ Kapso client initialized"
+    puts "📱 Phone Number ID: #{client.phone_number_id}"
+    puts "🏢 Business Account ID: #{client.business_account_id}"
+    
+    # Test API connection
+    begin
+      templates = client.templates.list(limit: 1)
+      puts "✅ API connection successful"
+      puts "📋 Found #{templates.dig('data')&.length || 0} templates"
+    rescue => e
+      puts "❌ API connection failed: #{e.message}"
+      exit 1
+    end
+    
+    # Send test message if phone number is provided
+    test_number = ENV['KAPSO_TEST_PHONE_NUMBER']
+    if test_number
+      puts "\n📤 Sending test message to #{test_number}..."
+      service = KapsoMessageService.new
+      service.send_test_message
+    else
+      puts "\n💡 Set KAPSO_TEST_PHONE_NUMBER to test messaging"
+    end
+  end
+
+  desc 'List available WhatsApp message templates'
+  task templates: :environment do
+    puts "📋 Fetching WhatsApp templates..."
+    
+    service = KapsoMessageService.new
+    templates_response = service.list_templates
+    
+    if templates_response && templates_response['data']
+      templates = templates_response['data']
+      puts "Found #{templates.length} templates:\n\n"
+      
+      templates.each do |template|
+        puts "📄 #{template['name']}"
+        puts "   Status: #{template['status']}"
+        puts "   Language: #{template['language']}"
+        puts "   Category: #{template['category']}"
+        puts "   Created: #{Time.at(template['created_time']).to_s}" if template['created_time']
+        puts ""
+      end
+    else
+      puts "❌ Failed to fetch templates or no templates found"
+    end
+  end
+
+  desc 'Check message status'
+  task :message_status, [:message_id] => :environment do |task, args|
+    message_id = args[:message_id]
+    
+    unless message_id
+      puts "❌ Please provide a message ID: rake kapso:message_status[message_id]"
+      exit 1
+    end
+    
+    puts "🔍 Checking status for message: #{message_id}"
+    
+    service = KapsoMessageService.new
+    status = service.get_message_status(message_id)
+    
+    if status
+      puts "📊 Message Status:"
+      puts "   ID: #{status['id']}"
+      puts "   Status: #{status['status']}"
+      puts "   Timestamp: #{Time.at(status['timestamp']).to_s}" if status['timestamp']
+      puts "   Recipient: #{status['recipient_id']}" if status['recipient_id']
+      
+      if status['errors']
+        puts "   Errors: #{status['errors']}"
+      end
+    else
+      puts "❌ Failed to get message status"
+    end
+  end
+
+  desc 'Validate webhook configuration'
+  task validate_webhook: :environment do
+    puts "🔗 Validating webhook configuration..."
+    
+    # Check required environment variables
+    required_vars = %w[KAPSO_WEBHOOK_VERIFY_TOKEN]
+    optional_vars = %w[KAPSO_WEBHOOK_SECRET]
+    
+    required_vars.each do |var|
+      if ENV[var].present?
+        puts "✅ #{var} is set"
+      else
+        puts "❌ #{var} is not set (required)"
+      end
+    end
+    
+    optional_vars.each do |var|
+      if ENV[var].present?
+        puts "✅ #{var} is set (recommended for security)"
+      else
+        puts "⚠️  #{var} is not set (optional but recommended)"
+      end
+    end
+    
+    # Check if routes are properly configured
+    begin
+      webhook_path = Rails.application.routes.url_helpers.kapso_webhooks_path rescue nil
+      if webhook_path
+        puts "✅ Webhook routes are configured"
+        puts "   Webhook URL: #{Rails.application.config.force_ssl ? 'https' : 'http'}://yourapp.com#{webhook_path}"
+      else
+        puts "⚠️  Webhook routes may not be configured. Make sure to add:"
+        puts "     post '/webhooks/kapso', to: 'kapso_webhooks#create'"
+        puts "     get '/webhooks/kapso', to: 'kapso_webhooks#verify'"
+      end
+    rescue => e
+      puts "⚠️  Could not check webhook routes: #{e.message}"
+    end
+  end
+
+  desc 'Generate sample environment file'
+  task :sample_env do
+    puts "📝 Generating .env.kapso.sample file..."
+    
+    env_content = <<~ENV
+      # Kapso API Configuration
+      # Copy this to your .env file and fill in your actual values
+      
+      # Required: Your Kapso API access token
+      KAPSO_API_KEY=your_api_key_here
+      
+      # Required: Your WhatsApp Business phone number ID  
+      KAPSO_PHONE_NUMBER_ID=your_phone_number_id_here
+      
+      # Required: Your WhatsApp Business account ID
+      KAPSO_BUSINESS_ACCOUNT_ID=your_business_account_id_here
+      
+      # Optional: API configuration
+      KAPSO_API_HOST=https://graph.facebook.com
+      KAPSO_API_VERSION=v18.0
+      KAPSO_TIMEOUT=30
+      
+      # Optional: Debug and retry settings
+      KAPSO_DEBUG=false
+      KAPSO_RETRY_ON_FAILURE=true
+      KAPSO_MAX_RETRIES=3
+      
+      # Webhook configuration
+      KAPSO_WEBHOOK_VERIFY_TOKEN=your_webhook_verify_token_here
+      KAPSO_WEBHOOK_SECRET=your_webhook_secret_here
+      
+      # Testing
+      KAPSO_TEST_PHONE_NUMBER=+1234567890
+    ENV
+    
+    File.write('.env.kapso.sample', env_content)
+    puts "✅ Created .env.kapso.sample"
+    puts "💡 Copy this to .env and update with your actual credentials"
+  end
+end

data/lib/kapso_client_ruby/version.rb

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

data/lib/kapso_client_ruby.rb

@@ -12,6 +12,12 @@ require_relative 'kapso_client_ruby/resources/calls'
 require_relative 'kapso_client_ruby/resources/conversations'
 require_relative 'kapso_client_ruby/resources/contacts'
 
+# Load Rails integration if Rails is available
+if defined?(Rails)
+  require_relative 'kapso_client_ruby/rails/railtie'
+  require_relative 'kapso_client_ruby/rails/service'
+end
+
 module KapsoClientRuby
   class << self
     # Configure default logging

data/scripts/kapso_template_finder.rb

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 require 'dotenv/load' rescue nil
-require_relative '../lib/whatsapp_cloud_api'
+require_relative '../lib/kapso_client_ruby'
 
 puts "🔍 Kapso Template Finder"
 puts "=" * 30
@@ -16,7 +16,7 @@ unless kapso_api_key && phone_number_id
   exit 1
 end
 
-client = WhatsAppCloudApi::Client.new(
+client = KapsoClientRuby::Client.new(
   kapso_api_key: kapso_api_key,
   base_url: ENV['WHATSAPP_BASE_URL'] || 'https://app.kapso.ai/api/meta'
 )

data/scripts/sdk_setup.rb

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require_relative '../lib/whatsapp_cloud_api'
+require_relative '../lib/kapso_client_ruby'
 
 puts "=== Kapso.ai and WhatsApp Cloud API Ruby SDK Setup ==="
 puts
@@ -106,7 +106,7 @@ puts "-" * 40
 begin
   # Initialize client based on configured environment
   if ENV['KAPSO_API_KEY']
-    client = WhatsAppCloudApi::Client.new(
+    client = KapsoClientRuby::Client.new(
       kapso_api_key: ENV['KAPSO_API_KEY'],
       base_url: 'https://app.kapso.ai/api/meta',
       debug: true
@@ -114,7 +114,7 @@ begin
     puts "✅ Kapso client initialized"
     puts "   Kapso proxy: #{client.kapso_proxy?}"
   else
-    client = WhatsAppCloudApi::Client.new(
+    client = KapsoClientRuby::Client.new(
       access_token: ENV['WHATSAPP_ACCESS_TOKEN'],
       debug: true
     )
@@ -135,7 +135,7 @@ puts "2. Testing Resource Access"
 puts "-" * 40
 
 begin
-  client = WhatsAppCloudApi::Client.new(access_token: 'test_token')
+  client = KapsoClientRuby::Client.new(access_token: 'test_token')
   
   # Test all resource accessors
   resources = {
@@ -168,16 +168,16 @@ puts "-" * 40
 
 begin
   # Test global configuration
-  WhatsAppCloudApi.configure do |config|
+  KapsoClientRuby.configure do |config|
     config.debug = true
     config.timeout = 45
     config.access_token = 'global_test_token'
   end
   
   puts "✅ Global configuration set"
-  puts "   Debug: #{WhatsAppCloudApi.configuration.debug}"
-  puts "   Timeout: #{WhatsAppCloudApi.configuration.timeout}"
-  puts "   Access token present: #{!WhatsAppCloudApi.configuration.access_token.nil?}"
+  puts "   Debug: #{KapsoClientRuby.configuration.debug}"
+  puts "   Timeout: #{KapsoClientRuby.configuration.timeout}"
+  puts "   Access token present: #{!KapsoClientRuby.configuration.access_token.nil?}"
   
 rescue => e
   puts "❌ Configuration failed: #{e.message}"
@@ -191,7 +191,7 @@ puts "-" * 40
 
 begin
   # Test creating different error types
-  rate_limit_error = WhatsAppCloudApi::Errors::GraphApiError.new(
+  rate_limit_error = KapsoClientRuby::Errors::GraphApiError.new(
     message: 'Rate limit exceeded',
     code: 4,
     http_status: 429,
@@ -204,7 +204,7 @@ begin
   puts "   Retry after: #{rate_limit_error.retry_after}s"
   puts "   Retry hint: #{rate_limit_error.retry_hint}"
   
-  auth_error = WhatsAppCloudApi::Errors::GraphApiError.new(
+  auth_error = KapsoClientRuby::Errors::GraphApiError.new(
     message: 'Invalid access token',
     code: 190,
     http_status: 401
@@ -234,11 +234,11 @@ begin
   puts "   Available methods: send_text, send_image, send_template, etc."
   
   # Test media types validation
-  media_types = WhatsAppCloudApi::Types::MEDIA_TYPES
+  media_types = KapsoClientRuby::Types::MEDIA_TYPES
   puts "✅ Media types supported: #{media_types.join(', ')}"
   
   # Test template statuses
-  template_statuses = WhatsAppCloudApi::Types::TEMPLATE_STATUSES
+  template_statuses = KapsoClientRuby::Types::TEMPLATE_STATUSES
   puts "✅ Template statuses: #{template_statuses.join(', ')}"
   
 rescue => e
@@ -252,12 +252,12 @@ puts "6. Testing Logger System"
 puts "-" * 40
 
 begin
-  logger = WhatsAppCloudApi.logger
+  logger = KapsoClientRuby.logger
   puts "✅ Logger accessible"
   puts "   Logger class: #{logger.class}"
   
   # Test logging (will show in console if debug enabled)
-  WhatsAppCloudApi.logger.info("SDK test completed successfully!")
+  KapsoClientRuby.logger.info("SDK test completed successfully!")
   
 rescue => e
   puts "❌ Logger test failed: #{e.message}"
@@ -310,7 +310,7 @@ if test_real_api
       puts "   Message Status: #{response.messages.first.message_status}"
     end
     
-  rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  rescue KapsoClientRuby::Errors::GraphApiError => e
     puts "❌ API Error: #{e.message}"
     puts "   Category: #{e.category}"
     puts "   HTTP Status: #{e.http_status}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kapso-client-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - PabloB07
@@ -203,6 +203,7 @@ files:
 - ".rubocop.yml"
 - CHANGELOG.md
 - Gemfile
+- RAILS_INTEGRATION.md
 - README.md
 - Rakefile
 - TEMPLATE_TOOLS_GUIDE.md
@@ -210,10 +211,21 @@ files:
 - examples/advanced_features.rb
 - examples/basic_messaging.rb
 - examples/media_management.rb
+- examples/rails/jobs.rb
+- examples/rails/models.rb
+- examples/rails/notifications_controller.rb
 - examples/template_management.rb
 - lib/kapso_client_ruby.rb
 - lib/kapso_client_ruby/client.rb
 - lib/kapso_client_ruby/errors.rb
+- lib/kapso_client_ruby/rails/generators/install_generator.rb
+- lib/kapso_client_ruby/rails/generators/templates/env.erb
+- lib/kapso_client_ruby/rails/generators/templates/initializer.rb.erb
+- lib/kapso_client_ruby/rails/generators/templates/message_service.rb.erb
+- lib/kapso_client_ruby/rails/generators/templates/webhook_controller.rb.erb
+- lib/kapso_client_ruby/rails/railtie.rb
+- lib/kapso_client_ruby/rails/service.rb
+- lib/kapso_client_ruby/rails/tasks.rake
 - lib/kapso_client_ruby/resources/calls.rb
 - lib/kapso_client_ruby/resources/contacts.rb
 - lib/kapso_client_ruby/resources/conversations.rb