whatsapp-cloud-api-ruby 1.0.0

data/lib/whatsapp_cloud_api/resources/phone_numbers.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module WhatsAppCloudApi
+  module Resources
+    class PhoneNumbers
+      def initialize(client)
+        @client = client
+      end
+
+      # Request verification code
+      def request_code(phone_number_id:, code_method:, language: 'en_US')
+        validate_code_method(code_method)
+        
+        payload = {
+          code_method: code_method.upcase,
+          language: language
+        }
+        
+        response = @client.request(:post, "#{phone_number_id}/request_code", 
+                                   body: payload.to_json, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Verify the received code
+      def verify_code(phone_number_id:, code:)
+        raise ArgumentError, 'Verification code cannot be empty' if code.nil? || code.strip.empty?
+        
+        payload = { code: code.to_s }
+        
+        response = @client.request(:post, "#{phone_number_id}/verify_code", 
+                                   body: payload.to_json, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Register phone number
+      def register(phone_number_id:, pin:, data_localization_region: nil)
+        raise ArgumentError, 'PIN cannot be empty' if pin.nil? || pin.strip.empty?
+        
+        payload = { pin: pin.to_s }
+        payload[:data_localization_region] = data_localization_region if data_localization_region
+        
+        response = @client.request(:post, "#{phone_number_id}/register", 
+                                   body: payload.to_json, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Deregister phone number
+      def deregister(phone_number_id:)
+        response = @client.request(:post, "#{phone_number_id}/deregister", 
+                                   body: {}.to_json, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Update phone number settings
+      def update_settings(phone_number_id:, messaging_product: 'whatsapp', 
+                          webhooks: nil, application: nil)
+        payload = { messaging_product: messaging_product }
+        payload[:webhooks] = webhooks if webhooks
+        payload[:application] = application if application
+        
+        response = @client.request(:post, phone_number_id, 
+                                   body: payload.to_json, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Get phone number info
+      def get(phone_number_id:, fields: nil)
+        query_params = {}
+        query_params[:fields] = fields if fields
+        
+        response = @client.request(:get, phone_number_id, 
+                                   query: query_params, response_type: :json)
+        response
+      end
+
+      private
+
+      def validate_code_method(method)
+        valid_methods = %w[SMS VOICE]
+        unless valid_methods.include?(method.to_s.upcase)
+          raise ArgumentError, "Invalid code method '#{method}'. Must be one of: #{valid_methods.join(', ')}"
+        end
+      end
+    end
+  end
+end

data/lib/whatsapp_cloud_api/resources/templates.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+module WhatsAppCloudApi
+  module Resources
+    class Templates
+      def initialize(client)
+        @client = client
+      end
+
+      # List templates for a business account
+      def list(business_account_id:, limit: nil, after: nil, before: nil, 
+               name: nil, status: nil, category: nil, language: nil, 
+               name_or_content: nil, quality_score: nil)
+        query_params = {
+          limit: limit,
+          after: after,
+          before: before,
+          name: name,
+          status: status,
+          category: category,
+          language: language,
+          name_or_content: name_or_content,
+          quality_score: quality_score
+        }.compact
+        
+        response = @client.request(:get, "#{business_account_id}/message_templates", 
+                                   query: query_params, response_type: :json)
+        Types::PagedResponse.new(response, Types::MessageTemplate)
+      end
+
+      # Get a specific template
+      def get(business_account_id:, template_id:, fields: nil)
+        query_params = {}
+        query_params[:fields] = fields if fields
+        
+        response = @client.request(:get, "#{business_account_id}/message_templates/#{template_id}", 
+                                   query: query_params, response_type: :json)
+        Types::MessageTemplate.new(response)
+      end
+
+      # Create a new template
+      def create(business_account_id:, name:, language:, category:, components:, 
+                 allow_category_change: nil, message_send_ttl_seconds: nil)
+        validate_template_data(name: name, language: language, category: category, components: components)
+        
+        payload = {
+          name: name,
+          language: language,
+          category: category,
+          components: normalize_components(components)
+        }
+        
+        payload[:allow_category_change] = allow_category_change unless allow_category_change.nil?
+        payload[:message_send_ttl_seconds] = message_send_ttl_seconds if message_send_ttl_seconds
+        
+        response = @client.request(:post, "#{business_account_id}/message_templates", 
+                                   body: payload.to_json, response_type: :json)
+        Types::TemplateCreateResponse.new(response)
+      end
+
+      # Update a template
+      def update(business_account_id:, template_id:, category: nil, components: nil)
+        payload = {}
+        payload[:category] = category if category
+        payload[:components] = normalize_components(components) if components
+        
+        return if payload.empty?
+        
+        response = @client.request(:post, "#{business_account_id}/message_templates/#{template_id}", 
+                                   body: payload.to_json, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Delete a template
+      def delete(business_account_id:, name: nil, template_id: nil, hsm_id: nil, language: nil)
+        if template_id
+          # Delete by template ID
+          response = @client.request(:delete, "#{business_account_id}/message_templates/#{template_id}", 
+                                     response_type: :json)
+        elsif name
+          # Delete by name and language
+          query_params = { name: name }
+          query_params[:language] = language if language
+          query_params[:hsm_id] = hsm_id if hsm_id
+          
+          response = @client.request(:delete, "#{business_account_id}/message_templates", 
+                                     query: query_params, response_type: :json)
+        else
+          raise ArgumentError, 'Must provide either template_id or name'
+        end
+        
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Template builder helpers
+      def build_text_component(text:, example: nil)
+        component = { type: 'BODY', text: text }
+        component[:example] = example if example
+        component
+      end
+
+      def build_header_component(type:, text: nil, image: nil, video: nil, 
+                                 document: nil, example: nil)
+        component = { type: 'HEADER', format: type.upcase }
+        
+        case type.upcase
+        when 'TEXT'
+          component[:text] = text if text
+        when 'IMAGE'
+          component[:example] = { header_handle: [image] } if image
+        when 'VIDEO'
+          component[:example] = { header_handle: [video] } if video
+        when 'DOCUMENT'
+          component[:example] = { header_handle: [document] } if document
+        end
+        
+        component[:example] = example if example
+        component
+      end
+
+      def build_footer_component(text: nil, code_expiration_minutes: nil)
+        component = { type: 'FOOTER' }
+        component[:text] = text if text
+        component[:code_expiration_minutes] = code_expiration_minutes if code_expiration_minutes
+        component
+      end
+
+      def build_buttons_component(buttons:)
+        {
+          type: 'BUTTONS',
+          buttons: buttons.map { |btn| normalize_button(btn) }
+        }
+      end
+
+      def build_button(type:, text: nil, url: nil, phone_number: nil, 
+                       otp_type: nil, autofill_text: nil, package_name: nil, 
+                       signature_hash: nil)
+        button = { type: type.upcase }
+        
+        case type.upcase
+        when 'QUICK_REPLY'
+          button[:text] = text if text
+        when 'URL'
+          button[:text] = text if text
+          button[:url] = url if url
+        when 'PHONE_NUMBER'
+          button[:text] = text if text
+          button[:phone_number] = phone_number if phone_number
+        when 'OTP'
+          button[:otp_type] = otp_type if otp_type
+          button[:text] = text if text
+          button[:autofill_text] = autofill_text if autofill_text
+          button[:package_name] = package_name if package_name
+          button[:signature_hash] = signature_hash if signature_hash
+        end
+        
+        button
+      end
+
+      # Authentication template builder
+      def build_authentication_template(name:, language:, ttl_seconds: 60, 
+                                        add_security_recommendation: true,
+                                        code_expiration_minutes: 10,
+                                        otp_type: 'COPY_CODE')
+        components = []
+        
+        # Body component with security recommendation
+        body_component = { type: 'BODY' }
+        body_component[:add_security_recommendation] = add_security_recommendation
+        components << body_component
+        
+        # Footer component with expiration
+        if code_expiration_minutes
+          components << build_footer_component(code_expiration_minutes: code_expiration_minutes)
+        end
+        
+        # OTP button
+        components << build_buttons_component(
+          buttons: [build_button(type: 'OTP', otp_type: otp_type)]
+        )
+        
+        {
+          name: name,
+          language: language,
+          category: 'AUTHENTICATION',
+          message_send_ttl_seconds: ttl_seconds,
+          components: components
+        }
+      end
+
+      # Marketing template builder
+      def build_marketing_template(name:, language:, header: nil, body:, footer: nil, 
+                                   buttons: nil, body_example: nil)
+        components = []
+        
+        # Header component
+        components << header if header
+        
+        # Body component
+        body_component = build_text_component(text: body, example: body_example)
+        components << body_component
+        
+        # Footer component
+        components << build_footer_component(text: footer) if footer
+        
+        # Buttons component
+        components << build_buttons_component(buttons: buttons) if buttons
+        
+        {
+          name: name,
+          language: language,
+          category: 'MARKETING',
+          components: components
+        }
+      end
+
+      # Utility template builder
+      def build_utility_template(name:, language:, body:, header: nil, footer: nil, 
+                                 buttons: nil, body_example: nil)
+        components = []
+        
+        # Header component
+        components << header if header
+        
+        # Body component
+        body_component = build_text_component(text: body, example: body_example)
+        components << body_component
+        
+        # Footer component
+        components << build_footer_component(text: footer) if footer
+        
+        # Buttons component
+        components << build_buttons_component(buttons: buttons) if buttons
+        
+        {
+          name: name,
+          language: language,
+          category: 'UTILITY',
+          components: components
+        }
+      end
+
+      private
+
+      def validate_template_data(name:, language:, category:, components:)
+        raise ArgumentError, 'Template name cannot be empty' if name.nil? || name.strip.empty?
+        raise ArgumentError, 'Language cannot be empty' if language.nil? || language.strip.empty?
+        raise ArgumentError, 'Category cannot be empty' if category.nil? || category.strip.empty?
+        raise ArgumentError, 'Components cannot be empty' if components.nil? || components.empty?
+        
+        # Validate category
+        valid_categories = Types::TEMPLATE_CATEGORIES
+        unless valid_categories.include?(category.upcase)
+          raise ArgumentError, "Invalid category '#{category}'. Must be one of: #{valid_categories.join(', ')}"
+        end
+        
+        # Validate components structure
+        components.each_with_index do |component, index|
+          unless component.is_a?(Hash) && component[:type]
+            raise ArgumentError, "Component at index #{index} must be a Hash with :type key"
+          end
+        end
+      end
+
+      def normalize_components(components)
+        components.map { |component| normalize_component(component) }
+      end
+
+      def normalize_component(component)
+        # Ensure component keys are strings for API compatibility
+        normalized = {}
+        component.each { |key, value| normalized[key.to_s] = value }
+        normalized
+      end
+
+      def normalize_button(button)
+        # Ensure button keys are strings for API compatibility
+        normalized = {}
+        button.each { |key, value| normalized[key.to_s] = value }
+        normalized
+      end
+    end
+  end
+end

data/lib/whatsapp_cloud_api/types.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module WhatsAppCloudApi
+  module Types
+    # Message status types
+    MESSAGE_STATUSES = %w[accepted held_for_quality_assessment].freeze
+
+    # Template status types
+    TEMPLATE_STATUSES = %w[APPROVED PENDING REJECTED PAUSED IN_APPEAL DISABLED].freeze
+
+    # Template categories
+    TEMPLATE_CATEGORIES = %w[MARKETING UTILITY AUTHENTICATION UNKNOWN].freeze
+
+    # Media types
+    MEDIA_TYPES = %w[image audio video document sticker].freeze
+
+    # Interactive message types
+    INTERACTIVE_TYPES = %w[button list product product_list flow address location_request call_permission].freeze
+
+    # Message response structure
+    class SendMessageResponse
+      attr_reader :messaging_product, :contacts, :messages
+
+      def initialize(data)
+        @messaging_product = data['messaging_product']
+        @contacts = data['contacts']&.map { |c| MessageContact.new(c) } || []
+        @messages = data['messages']&.map { |m| MessageInfo.new(m) } || []
+      end
+    end
+
+    class MessageContact
+      attr_reader :input, :wa_id
+
+      def initialize(data)
+        @input = data['input']
+        @wa_id = data['wa_id']
+      end
+    end
+
+    class MessageInfo
+      attr_reader :id, :message_status
+
+      def initialize(data)
+        @id = data['id']
+        @message_status = data['message_status']
+      end
+    end
+
+    # Media response structures
+    class MediaUploadResponse
+      attr_reader :id
+
+      def initialize(data)
+        @id = data['id']
+      end
+    end
+
+    class MediaMetadataResponse
+      attr_reader :messaging_product, :url, :mime_type, :sha256, :file_size, :id
+
+      def initialize(data)
+        @messaging_product = data['messaging_product']
+        @url = data['url']
+        @mime_type = data['mime_type']
+        @sha256 = data['sha256']
+        @file_size = data['file_size']
+        @id = data['id']
+      end
+    end
+
+    # Template structures
+    class MessageTemplate
+      attr_reader :id, :name, :category, :language, :status, :components, 
+                  :quality_score_category, :warnings, :previous_category, 
+                  :library_template_name, :last_updated_time
+
+      def initialize(data)
+        @id = data['id']
+        @name = data['name']
+        @category = data['category']
+        @language = data['language']
+        @status = data['status']
+        @components = data['components']
+        @quality_score_category = data['quality_score_category']
+        @warnings = data['warnings']
+        @previous_category = data['previous_category']
+        @library_template_name = data['library_template_name']
+        @last_updated_time = data['last_updated_time']
+      end
+    end
+
+    class TemplateCreateResponse
+      attr_reader :id, :status, :category
+
+      def initialize(data)
+        @id = data['id']
+        @status = data['status']
+        @category = data['category']
+      end
+    end
+
+    # Paging structures
+    class GraphPaging
+      attr_reader :cursors, :next_page, :previous_page
+
+      def initialize(data)
+        @cursors = data['cursors'] || {}
+        @next_page = data['next']
+        @previous_page = data['previous']
+      end
+
+      def before
+        cursors['before']
+      end
+
+      def after
+        cursors['after']
+      end
+    end
+
+    class PagedResponse
+      attr_reader :data, :paging
+
+      def initialize(data, item_class = nil)
+        @data = if item_class && data['data'].is_a?(Array)
+                  data['data'].map { |item| item_class.new(item) }
+                else
+                  data['data'] || []
+                end
+        @paging = GraphPaging.new(data['paging'] || {})
+      end
+    end
+
+    # Success response
+    class GraphSuccessResponse
+      attr_reader :success
+
+      def initialize(data = nil)
+        @success = data.nil? || data['success'] || true
+      end
+
+      def success?
+        @success
+      end
+    end
+
+    # Business profile structures
+    class BusinessProfileEntry
+      attr_reader :about, :address, :description, :email, :websites, 
+                  :vertical, :profile_picture_url, :profile_picture_handle
+
+      def initialize(data)
+        @about = data['about']
+        @address = data['address']
+        @description = data['description']
+        @email = data['email']
+        @websites = data['websites']
+        @vertical = data['vertical']
+        @profile_picture_url = data['profile_picture_url']
+        @profile_picture_handle = data['profile_picture_handle']
+      end
+    end
+
+    # Conversation structures
+    class ConversationRecord
+      attr_reader :id, :phone_number, :phone_number_id, :status, :last_active_at, 
+                  :kapso, :metadata
+
+      def initialize(data)
+        @id = data['id']
+        @phone_number = data['phone_number']
+        @phone_number_id = data['phone_number_id']
+        @status = data['status']
+        @last_active_at = data['last_active_at']
+        @kapso = data['kapso']
+        @metadata = data['metadata']
+      end
+    end
+
+    # Contact structures
+    class ContactRecord
+      attr_reader :wa_id, :phone_number, :profile_name, :metadata
+
+      def initialize(data)
+        @wa_id = data['wa_id']
+        @phone_number = data['phone_number']
+        @profile_name = data['profile_name']
+        @metadata = data['metadata']
+      end
+    end
+
+    # Call structures
+    class CallRecord
+      attr_reader :id, :direction, :status, :duration_seconds, :started_at, 
+                  :ended_at, :whatsapp_conversation_id, :whatsapp_contact_id
+
+      def initialize(data)
+        @id = data['id']
+        @direction = data['direction']
+        @status = data['status']
+        @duration_seconds = data['duration_seconds']
+        @started_at = data['started_at']
+        @ended_at = data['ended_at']
+        @whatsapp_conversation_id = data['whatsapp_conversation_id']
+        @whatsapp_contact_id = data['whatsapp_contact_id']
+      end
+    end
+
+    class CallConnectResponse
+      attr_reader :messaging_product, :calls
+
+      def initialize(data)
+        @messaging_product = data['messaging_product']
+        @calls = data['calls'] || []
+      end
+    end
+
+    class CallActionResponse < GraphSuccessResponse
+      attr_reader :messaging_product
+
+      def initialize(data)
+        super(data)
+        @messaging_product = data['messaging_product']
+      end
+    end
+
+    # Utility method to convert snake_case to camelCase for API requests
+    def self.to_camel_case(str)
+      str.split('_').map.with_index { |word, i| i == 0 ? word : word.capitalize }.join
+    end
+
+    # Utility method to convert camelCase to snake_case for Ruby conventions
+    def self.to_snake_case(str)
+      str.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, '')
+    end
+
+    # Deep convert hash keys from camelCase to snake_case
+    def self.deep_snake_case_keys(obj)
+      case obj
+      when Hash
+        obj.transform_keys { |key| to_snake_case(key.to_s) }
+           .transform_values { |value| deep_snake_case_keys(value) }
+      when Array
+        obj.map { |item| deep_snake_case_keys(item) }
+      else
+        obj
+      end
+    end
+
+    # Deep convert hash keys from snake_case to camelCase
+    def self.deep_camel_case_keys(obj)
+      case obj
+      when Hash
+        obj.transform_keys { |key| to_camel_case(key.to_s) }
+           .transform_values { |value| deep_camel_case_keys(value) }
+      when Array
+        obj.map { |item| deep_camel_case_keys(item) }
+      else
+        obj
+      end
+    end
+  end
+end

data/lib/whatsapp_cloud_api/version.rb

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

data/lib/whatsapp_cloud_api.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative 'whatsapp_cloud_api/version'
+require_relative 'whatsapp_cloud_api/client'
+require_relative 'whatsapp_cloud_api/errors'
+require_relative 'whatsapp_cloud_api/types'
+require_relative 'whatsapp_cloud_api/resources/messages'
+require_relative 'whatsapp_cloud_api/resources/media'
+require_relative 'whatsapp_cloud_api/resources/templates'
+require_relative 'whatsapp_cloud_api/resources/phone_numbers'
+require_relative 'whatsapp_cloud_api/resources/calls'
+require_relative 'whatsapp_cloud_api/resources/conversations'
+require_relative 'whatsapp_cloud_api/resources/contacts'
+
+module WhatsAppCloudApi
+  class << self
+    # Configure default logging
+    def logger
+      @logger ||= Logger.new($stdout).tap do |log|
+        log.level = Logger::INFO
+        log.formatter = proc do |severity, datetime, progname, msg|
+          "[#{datetime}] #{severity} #{progname}: #{msg}\n"
+        end
+      end
+    end
+
+    def logger=(logger)
+      @logger = logger
+    end
+
+    # Global configuration
+    def configure
+      yield(configuration)
+    end
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+
+  class Configuration
+    attr_accessor :debug, :timeout, :open_timeout, :max_retries, :retry_delay,
+                  :access_token, :kapso_api_key, :base_url, :api_version
+
+    def initialize
+      @debug = false
+      @timeout = 60
+      @open_timeout = 10
+      @max_retries = 3
+      @retry_delay = 1.0
+      @base_url = 'https://graph.facebook.com'
+      @api_version = 'v23.0'
+      @access_token = nil
+      @kapso_api_key = nil
+    end
+
+    def kapso_proxy?
+      !@kapso_api_key.nil? && @base_url&.include?('kapso')
+    end
+
+    def valid?
+      !@access_token.nil? || !@kapso_api_key.nil?
+    end
+  end
+end