kapso-client-ruby 1.0.0 → 1.0.2

data/lib/kapso_client_ruby/rails/generators/install_generator.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module KapsoClientRuby
+  module Rails
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path('templates', __dir__)
+
+        desc 'Install KapsoClientRuby in a Rails application'
+
+        def create_initializer
+          template 'initializer.rb.erb', 'config/initializers/kapso_client_ruby.rb'
+        end
+
+        def create_env_example
+          template 'env.erb', '.env.example'
+        end
+
+        def create_webhook_controller
+          template 'webhook_controller.rb.erb', 'app/controllers/kapso_webhooks_controller.rb'
+        end
+
+        def create_service_example
+          template 'message_service.rb.erb', 'app/services/kapso_message_service.rb'
+        end
+
+        def add_routes
+          route <<~RUBY
+            # Kapso webhook endpoint
+            post '/webhooks/kapso', to: 'kapso_webhooks#create'
+            get '/webhooks/kapso', to: 'kapso_webhooks#verify' # For webhook verification
+          RUBY
+        end
+
+        def show_readme
+          say <<~MESSAGE
+
+            KapsoClientRuby has been successfully installed!
+
+            Next steps:
+            1. Add your Kapso credentials to your environment variables:
+               - KAPSO_API_KEY
+               - KAPSO_PHONE_NUMBER_ID
+               - KAPSO_BUSINESS_ACCOUNT_ID
+
+            2. Review and customize the generated files:
+               - config/initializers/kapso_client_ruby.rb
+               - app/controllers/kapso_webhooks_controller.rb
+               - app/services/kapso_message_service.rb
+
+            3. Set up your webhook URL in the Kapso dashboard:
+               https://yourapp.com/webhooks/kapso
+
+            4. Test the integration:
+               rails runner "KapsoMessageService.new.send_test_message"
+
+            For more information, see: https://github.com/PabloB07/kapso-client-ruby
+
+          MESSAGE
+        end
+
+        private
+
+        def application_name
+          if defined?(Rails) && Rails.application
+            Rails.application.class.name.split('::').first
+          else
+            'YourApp'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kapso_client_ruby/rails/generators/templates/env.erb

@@ -0,0 +1,21 @@
+# Kapso API Configuration
+# Add these to your actual .env file (don't commit API keys to version control)
+
+# 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=v23.0
+KAPSO_TIMEOUT=30
+
+# Optional: Debug and retry settings
+KAPSO_DEBUG=false
+KAPSO_RETRY_ON_FAILURE=true
+KAPSO_MAX_RETRIES=3

data/lib/kapso_client_ruby/rails/generators/templates/initializer.rb.erb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# KapsoClientRuby configuration for Rails
+KapsoClientRuby.configure do |config|
+  # API credentials - set these in your environment variables
+  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
+
+  # Development/Debug settings
+  config.debug = Rails.env.development? || ENV.fetch('KAPSO_DEBUG', 'false') == 'true'
+  config.logger = Rails.logger
+
+  # Retry configuration
+  config.retry_on_failure = ENV.fetch('KAPSO_RETRY_ON_FAILURE', 'true') == 'true'
+  config.max_retries = ENV.fetch('KAPSO_MAX_RETRIES', 3).to_i
+end
+
+# Subscribe to Kapso events (optional)
+# ActiveSupport::Notifications.subscribe('kapso.message_received') do |name, start, finish, id, payload|
+#   Rails.logger.info "Received WhatsApp message: #{payload[:message]['id']}"
+#   # Handle incoming message
+# end
+
+# ActiveSupport::Notifications.subscribe('kapso.message_status_updated') do |name, start, finish, id, payload|
+#   Rails.logger.info "Message status updated: #{payload[:status]['id']} -> #{payload[:status]['status']}"
+#   # Handle message status update
+# end

data/lib/kapso_client_ruby/rails/generators/templates/message_service.rb.erb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+# Example service class for sending WhatsApp messages in a Rails application
+# This wraps the KapsoClientRuby functionality with Rails-specific features
+class KapsoMessageService
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  # Initialize with optional custom client
+  def initialize(client: nil)
+    @kapso_service = KapsoClientRuby::Rails::Service.new(client)
+  end
+
+  # Send a welcome message to a new user
+  # @param user [User] The user to send the message to
+  # @return [Hash] API response
+  def send_welcome_message(user)
+    return unless user.phone_number.present?
+
+    @kapso_service.send_template_message(
+      to: user.phone_number,
+      template_name: 'welcome_message',
+      language: user.preferred_language || 'en',
+      components: [
+        {
+          type: 'body',
+          parameters: [
+            { type: 'text', text: user.first_name || 'there' }
+          ]
+        }
+      ]
+    )
+  rescue KapsoClientRuby::Error => e
+    Rails.logger.error "Failed to send welcome message to user #{user.id}: #{e.message}"
+    # You might want to queue for retry or notify admins
+    nil
+  end
+
+  # Send order confirmation
+  # @param order [Order] The order to confirm
+  # @return [Hash] API response
+  def send_order_confirmation(order)
+    user = order.user
+    return unless user.phone_number.present?
+
+    @kapso_service.send_template_message(
+      to: user.phone_number,
+      template_name: 'order_confirmation',
+      language: user.preferred_language || 'en',
+      components: [
+        {
+          type: 'body',
+          parameters: [
+            { type: 'text', text: order.id.to_s },
+            { type: 'currency', currency: order.currency, amount_1000: order.total_cents }
+          ]
+        }
+      ]
+    )
+  rescue KapsoClientRuby::Error => e
+    Rails.logger.error "Failed to send order confirmation for order #{order.id}: #{e.message}"
+    nil
+  end
+
+  # Send a custom text message
+  # @param phone_number [String] Recipient's phone number
+  # @param message [String] The message text
+  # @return [Hash] API response
+  def send_text(phone_number:, message:)
+    @kapso_service.send_text_message(to: phone_number, text: message)
+  rescue KapsoClientRuby::Error => e
+    Rails.logger.error "Failed to send text message to #{phone_number}: #{e.message}"
+    nil
+  end
+
+  # Send a document
+  # @param phone_number [String] Recipient's phone number
+  # @param document_url [String] URL of the document
+  # @param filename [String] Optional filename
+  # @param caption [String] Optional caption
+  # @return [Hash] API response
+  def send_document(phone_number:, document_url:, filename: nil, caption: nil)
+    @kapso_service.send_media_message(
+      to: phone_number,
+      media_type: 'document',
+      media_url: document_url,
+      filename: filename,
+      caption: caption
+    )
+  rescue KapsoClientRuby::Error => e
+    Rails.logger.error "Failed to send document to #{phone_number}: #{e.message}"
+    nil
+  end
+
+  # Send test message (for development/testing)
+  def send_test_message
+    test_number = ENV['KAPSO_TEST_PHONE_NUMBER']
+    
+    unless test_number
+      puts "Set KAPSO_TEST_PHONE_NUMBER environment variable to test messaging"
+      return
+    end
+
+    result = send_text(
+      phone_number: test_number,
+      message: "Hello from <%= application_name %>! This is a test message sent at #{Time.current}."
+    )
+
+    if result
+      puts "✅ Test message sent successfully! Message ID: #{result.dig('messages', 0, 'id')}"
+    else
+      puts "❌ Failed to send test message"
+    end
+  end
+
+  # Get message delivery status
+  # @param message_id [String] The message ID
+  # @return [Hash] Status information
+  def get_message_status(message_id)
+    @kapso_service.get_message_status(message_id)
+  rescue KapsoClientRuby::Error => e
+    Rails.logger.error "Failed to get message status for #{message_id}: #{e.message}"
+    nil
+  end
+
+  # List available templates
+  # @return [Array] List of templates
+  def list_templates
+    @kapso_service.get_templates
+  rescue KapsoClientRuby::Error => e
+    Rails.logger.error "Failed to fetch templates: #{e.message}"
+    nil
+  end
+
+  private
+
+  attr_reader :kapso_service
+end

data/lib/kapso_client_ruby/rails/generators/templates/webhook_controller.rb.erb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class KapsoWebhooksController < ApplicationController
+  # Skip CSRF token verification for webhook endpoints
+  skip_before_action :verify_authenticity_token
+
+  # Webhook verification endpoint (GET)
+  # WhatsApp sends a GET request to verify your webhook URL
+  def verify
+    challenge = params['hub.challenge']
+    verify_token = params['hub.verify_token']
+    
+    # Set your verification token in environment variables
+    expected_token = ENV['KAPSO_WEBHOOK_VERIFY_TOKEN']
+    
+    if verify_token == expected_token
+      render plain: challenge, status: :ok
+    else
+      render plain: 'Forbidden', status: :forbidden
+    end
+  end
+
+  # Webhook payload endpoint (POST)
+  # WhatsApp sends webhook events here
+  def create
+    begin
+      # Verify webhook signature (optional but recommended)
+      verify_webhook_signature if ENV['KAPSO_WEBHOOK_SECRET'].present?
+      
+      # Process the webhook using the Kapso Rails service
+      service = KapsoClientRuby::Rails::Service.new
+      result = service.process_webhook(webhook_params.to_h)
+      
+      render json: { status: 'ok' }, status: :ok
+    rescue => e
+      Rails.logger.error "Webhook processing error: #{e.message}"
+      render json: { error: 'Internal server error' }, status: :internal_server_error
+    end
+  end
+
+  private
+
+  def webhook_params
+    params.permit!
+  end
+
+  def verify_webhook_signature
+    signature = request.headers['X-Hub-Signature-256']
+    return unless signature
+
+    expected_signature = calculate_signature(request.raw_post)
+    
+    unless Rack::Utils.secure_compare(signature, expected_signature)
+      raise 'Invalid webhook signature'
+    end
+  end
+
+  def calculate_signature(payload)
+    secret = ENV['KAPSO_WEBHOOK_SECRET']
+    'sha256=' + OpenSSL::HMAC.hexdigest('sha256', secret, payload)
+  end
+end

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