kapso-client-ruby 1.0.0 → 1.0.1

data/examples/rails/notifications_controller.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+# Example Rails controller showing various WhatsApp integration patterns
+class NotificationsController < ApplicationController
+  before_action :authenticate_user!
+  before_action :ensure_phone_number, only: [:send_notification, :send_order_update]
+
+  # GET /notifications
+  # Show notification preferences and send test message
+  def index
+    @user = current_user
+    @message_service = KapsoMessageService.new
+    @templates = @message_service.list_templates&.dig('data') || []
+  end
+
+  # POST /notifications/test
+  # Send a test message to the current user
+  def send_test
+    service = KapsoMessageService.new
+    
+    begin
+      result = service.send_text(
+        phone_number: current_user.phone_number,
+        message: "Hello #{current_user.name}! This is a test message from #{Rails.application.class.name.deconstantize}."
+      )
+      
+      if result
+        flash[:success] = "Test message sent successfully! Message ID: #{result.dig('messages', 0, 'id')}"
+      else
+        flash[:error] = "Failed to send test message. Please check the logs."
+      end
+    rescue KapsoClientRuby::Error => e
+      flash[:error] = "Error sending message: #{e.message}"
+      Rails.logger.error "WhatsApp test message error: #{e.message}"
+    end
+    
+    redirect_to notifications_path
+  end
+
+  # POST /notifications/welcome
+  # Send welcome message using template
+  def send_welcome
+    service = KapsoMessageService.new
+    
+    begin
+      result = service.send_welcome_message(current_user)
+      
+      if result
+        flash[:success] = "Welcome message sent!"
+        
+        # Track the sent message
+        current_user.whatsapp_messages.create!(
+          message_id: result.dig('messages', 0, 'id'),
+          message_type: 'welcome',
+          status: 'sent',
+          sent_at: Time.current
+        )
+      else
+        flash[:error] = "Failed to send welcome message."
+      end
+    rescue KapsoClientRuby::Error => e
+      flash[:error] = "Error: #{e.message}"
+    end
+    
+    redirect_to notifications_path
+  end
+
+  # POST /notifications/custom
+  # Send custom message with template
+  def send_custom
+    template_name = params[:template_name]
+    custom_params = params[:template_params] || {}
+    
+    unless template_name.present?
+      flash[:error] = "Please select a template"
+      redirect_to notifications_path
+      return
+    end
+    
+    service = KapsoClientRuby::Rails::Service.new
+    
+    begin
+      # Build template components from form params
+      components = []
+      
+      if custom_params.present?
+        body_params = custom_params.values.map do |param|
+          { type: 'text', text: param.to_s }
+        end
+        
+        components << {
+          type: 'body',
+          parameters: body_params
+        } if body_params.any?
+      end
+      
+      result = service.send_template_message(
+        to: current_user.phone_number,
+        template_name: template_name,
+        language: current_user.preferred_language || 'en',
+        components: components
+      )
+      
+      flash[:success] = "Template message sent! ID: #{result.dig('messages', 0, 'id')}"
+      
+      # Log the message
+      Rails.logger.info "Template '#{template_name}' sent to #{current_user.phone_number}"
+      
+    rescue KapsoClientRuby::Error => e
+      flash[:error] = "Failed to send template: #{e.message}"
+      Rails.logger.error "Template send error: #{e.message}"
+    end
+    
+    redirect_to notifications_path
+  end
+
+  # POST /notifications/document
+  # Send a document to the user
+  def send_document
+    document_url = params[:document_url]
+    filename = params[:filename]
+    caption = params[:caption]
+    
+    unless document_url.present?
+      flash[:error] = "Document URL is required"
+      redirect_to notifications_path
+      return
+    end
+    
+    service = KapsoMessageService.new
+    
+    begin
+      result = service.send_document(
+        phone_number: current_user.phone_number,
+        document_url: document_url,
+        filename: filename,
+        caption: caption
+      )
+      
+      flash[:success] = "Document sent successfully!"
+      Rails.logger.info "Document sent to #{current_user.phone_number}: #{document_url}"
+      
+    rescue KapsoClientRuby::Error => e
+      flash[:error] = "Failed to send document: #{e.message}"
+    end
+    
+    redirect_to notifications_path
+  end
+
+  # GET /notifications/message_status/:message_id
+  # Check status of a sent message
+  def message_status
+    message_id = params[:id]
+    service = KapsoMessageService.new
+    
+    begin
+      status = service.get_message_status(message_id)
+      
+      if status
+        render json: {
+          message_id: status['id'],
+          status: status['status'],
+          timestamp: status['timestamp'],
+          recipient_id: status['recipient_id']
+        }
+      else
+        render json: { error: 'Message not found' }, status: :not_found
+      end
+    rescue KapsoClientRuby::Error => e
+      render json: { error: e.message }, status: :unprocessable_entity
+    end
+  end
+
+  # POST /notifications/bulk
+  # Send bulk messages (should be queued in production)
+  def send_bulk
+    recipients = params[:recipients]&.split(',')&.map(&:strip) || []
+    message = params[:message]
+    
+    if recipients.empty? || message.blank?
+      flash[:error] = "Recipients and message are required"
+      redirect_to notifications_path
+      return
+    end
+    
+    # In production, this should be done via background jobs
+    successful_sends = 0
+    failed_sends = 0
+    
+    recipients.each do |phone_number|
+      begin
+        service = KapsoMessageService.new
+        result = service.send_text(phone_number: phone_number, message: message)
+        
+        if result
+          successful_sends += 1
+          Rails.logger.info "Bulk message sent to #{phone_number}"
+        else
+          failed_sends += 1
+        end
+        
+        # Rate limiting - small delay between messages
+        sleep(0.5)
+        
+      rescue KapsoClientRuby::Error => e
+        failed_sends += 1
+        Rails.logger.error "Bulk message failed for #{phone_number}: #{e.message}"
+      end
+    end
+    
+    flash[:success] = "Bulk send complete: #{successful_sends} sent, #{failed_sends} failed"
+    redirect_to notifications_path
+  end
+
+  private
+
+  def ensure_phone_number
+    unless current_user.phone_number.present?
+      flash[:error] = "Please add a phone number to your profile first"
+      redirect_to edit_user_registration_path
+    end
+  end
+
+  def notification_params
+    params.permit(:message, :template_name, :document_url, :filename, :caption, :recipients, template_params: {})
+  end
+end

data/examples/template_management.rb

@@ -5,7 +5,7 @@ require 'whatsapp_cloud_api'
 puts "=== Template Management Examples ==="
 
 # Initialize client
-client = WhatsAppCloudApi::Client.new(
+client = KapsoClientRuby::Client.new(
   access_token: ENV['WHATSAPP_ACCESS_TOKEN']
 )
 
@@ -27,7 +27,7 @@ begin
     puts "\nMore templates available. Next cursor: #{templates.paging.after}"
   end
   
-rescue WhatsAppCloudApi::Errors::GraphApiError => e
+rescue KapsoClientRuby::Errors::GraphApiError => e
   puts "Error listing templates: #{e.message}"
 end
 
@@ -72,7 +72,7 @@ begin
   puts "Template ID: #{response.id}"
   puts "Status: #{response.status}"
   
-rescue WhatsAppCloudApi::Errors::GraphApiError => e
+rescue KapsoClientRuby::Errors::GraphApiError => e
   puts "Error creating marketing template: #{e.message}"
   
   if e.template_error?
@@ -102,7 +102,7 @@ begin
   puts "Template ID: #{response.id}"
   puts "Status: #{response.status}"
   
-rescue WhatsAppCloudApi::Errors::GraphApiError => e
+rescue KapsoClientRuby::Errors::GraphApiError => e
   puts "Error creating auth template: #{e.message}"
 end
 
@@ -140,7 +140,7 @@ begin
   puts "Utility template created!"
   puts "Template ID: #{response.id}"
   
-rescue WhatsAppCloudApi::Errors::GraphApiError => e
+rescue KapsoClientRuby::Errors::GraphApiError => e
   puts "Error creating utility template: #{e.message}"
 end
 
@@ -204,7 +204,7 @@ begin
   puts "Complex template created!"
   puts "Template ID: #{response.id}"
   
-rescue WhatsAppCloudApi::Errors::GraphApiError => e
+rescue KapsoClientRuby::Errors::GraphApiError => e
   puts "Error creating complex template: #{e.message}"
 end
 
@@ -257,7 +257,7 @@ begin
   
   puts "Parameterized template sent: #{response2.messages.first.id}"
   
-rescue WhatsAppCloudApi::Errors::GraphApiError => e
+rescue KapsoClientRuby::Errors::GraphApiError => e
   puts "Error sending template: #{e.message}"
   
   case e.category
@@ -299,7 +299,7 @@ begin
     puts "Template updated successfully"
   end
   
-rescue WhatsAppCloudApi::Errors::GraphApiError => e
+rescue KapsoClientRuby::Errors::GraphApiError => e
   puts "Template management error: #{e.message}"
 end
 
@@ -324,7 +324,7 @@ begin
   
   puts "Template deleted by name"
   
-rescue WhatsAppCloudApi::Errors::GraphApiError => e
+rescue KapsoClientRuby::Errors::GraphApiError => e
   puts "Delete error: #{e.message}"
   
   if e.http_status == 404
@@ -374,7 +374,7 @@ def create_bad_template_example(client, business_account_id)
         }
       ]
     )
-  rescue WhatsAppCloudApi::Errors::GraphApiError => e
+  rescue KapsoClientRuby::Errors::GraphApiError => e
     puts "Bad template rejected (expected): #{e.message}"
   end
 end

data/lib/kapso_client_ruby/client.rb

@@ -30,8 +30,8 @@ module KapsoClientRuby
       @kapso_proxy = detect_kapso_proxy(@base_url)
       
       # Configuration with defaults
-      config = WhatsAppCloudApi.configuration
-      @logger = logger || WhatsAppCloudApi.logger
+      config = KapsoClientRuby.configuration
+      @logger = logger || KapsoClientRuby.logger
       @debug = debug.nil? ? config.debug : debug
       @timeout = timeout || config.timeout
       @open_timeout = open_timeout || config.open_timeout

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=v18.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