whatsapp-cloud-api-ruby 1.0.0

data/lib/whatsapp_cloud_api/resources/conversations.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module WhatsAppCloudApi
+  module Resources
+    class Conversations
+      def initialize(client)
+        @client = client
+      end
+
+      # List conversations (Kapso Proxy only)
+      def list(phone_number_id:, status: nil, last_active_since: nil, 
+               last_active_until: nil, phone_number: nil, limit: nil, 
+               after: nil, before: nil, fields: nil)
+        assert_kapso_proxy('Conversations API')
+        
+        query_params = {
+          status: status,
+          last_active_since: last_active_since,
+          last_active_until: last_active_until,
+          phone_number: phone_number,
+          limit: limit,
+          after: after,
+          before: before,
+          fields: fields
+        }.compact
+        
+        response = @client.request(:get, "#{phone_number_id}/conversations", 
+                                   query: query_params, response_type: :json)
+        Types::PagedResponse.new(response, Types::ConversationRecord)
+      end
+
+      # Get conversation details (Kapso Proxy only)
+      def get(conversation_id:)
+        assert_kapso_proxy('Conversations API')
+        
+        raise ArgumentError, 'conversation_id cannot be empty' if conversation_id.nil? || conversation_id.strip.empty?
+        
+        response = @client.request(:get, "conversations/#{conversation_id}", 
+                                   response_type: :json)
+        
+        # Handle both single object and data envelope responses
+        if response.is_a?(Hash) && response.key?('data')
+          Types::ConversationRecord.new(response['data'])
+        else
+          Types::ConversationRecord.new(response)
+        end
+      end
+
+      # Update conversation status (Kapso Proxy only)
+      def update_status(conversation_id:, status:)
+        assert_kapso_proxy('Conversations API')
+        
+        raise ArgumentError, 'conversation_id cannot be empty' if conversation_id.nil? || conversation_id.strip.empty?
+        raise ArgumentError, 'status cannot be empty' if status.nil? || status.strip.empty?
+        
+        payload = { status: status }
+        
+        response = @client.request(:patch, "conversations/#{conversation_id}", 
+                                   body: payload.to_json, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Archive conversation (Kapso Proxy only)
+      def archive(conversation_id:)
+        update_status(conversation_id: conversation_id, status: 'archived')
+      end
+
+      # Unarchive conversation (Kapso Proxy only)
+      def unarchive(conversation_id:)
+        update_status(conversation_id: conversation_id, status: 'active')
+      end
+
+      # End conversation (Kapso Proxy only)
+      def end_conversation(conversation_id:)
+        update_status(conversation_id: conversation_id, status: 'ended')
+      end
+
+      # Get conversation analytics (Kapso Proxy only)
+      def analytics(phone_number_id:, conversation_id: nil, since: nil, 
+                    until_time: nil, granularity: 'day')
+        assert_kapso_proxy('Conversation Analytics API')
+        
+        query_params = {
+          conversation_id: conversation_id,
+          since: since,
+          until: until_time,
+          granularity: granularity
+        }.compact
+        
+        response = @client.request(:get, "#{phone_number_id}/conversations/analytics", 
+                                   query: query_params, response_type: :json)
+        response
+      end
+
+      private
+
+      def assert_kapso_proxy(feature)
+        unless @client.kapso_proxy?
+          raise Errors::KapsoProxyRequiredError.new(feature)
+        end
+      end
+    end
+  end
+end

data/lib/whatsapp_cloud_api/resources/media.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'mime/types'
+
+module WhatsAppCloudApi
+  module Resources
+    class Media
+      def initialize(client)
+        @client = client
+      end
+
+      # Upload media file
+      def upload(phone_number_id:, type:, file:, filename: nil, messaging_product: 'whatsapp', 
+                 upload_strategy: nil)
+        validate_media_type(type)
+        
+        # Build multipart form data
+        form_data = {
+          'messaging_product' => messaging_product,
+          'type' => type
+        }
+        
+        # Handle file parameter - can be File, IO, or file path string
+        file_obj = case file
+                   when String
+                     # Assume it's a file path
+                     File.open(file, 'rb')
+                   when File, IO, StringIO
+                     file
+                   else
+                     raise ArgumentError, 'file must be a File, IO object, or file path string'
+                   end
+        
+        # Determine filename and content type
+        if filename.nil? && file.is_a?(String)
+          filename = File.basename(file)
+        end
+        
+        content_type = determine_content_type(file_obj, filename, type)
+        
+        form_data['file'] = Faraday::UploadIO.new(file_obj, content_type, filename)
+        form_data['upload_strategy'] = upload_strategy if upload_strategy
+        
+        # Set multipart content type header
+        headers = { 'Content-Type' => 'multipart/form-data' }
+        
+        response = @client.request(:post, "#{phone_number_id}/media", 
+                                   body: form_data, headers: headers, response_type: :json)
+        
+        # Close file if we opened it
+        file_obj.close if file.is_a?(String) && file_obj.respond_to?(:close)
+        
+        Types::MediaUploadResponse.new(response)
+      end
+
+      # Get media metadata
+      def get(media_id:, phone_number_id: nil)
+        # phone_number_id is required for Kapso proxy
+        if @client.kapso_proxy? && phone_number_id.nil?
+          raise ArgumentError, 'phone_number_id is required when using Kapso proxy'
+        end
+        
+        query_params = {}
+        query_params[:phone_number_id] = phone_number_id if phone_number_id
+        
+        response = @client.request(:get, media_id, 
+                                   query: query_params, response_type: :json)
+        Types::MediaMetadataResponse.new(response)
+      end
+
+      # Delete media
+      def delete(media_id:, phone_number_id: nil)
+        # phone_number_id is required for Kapso proxy
+        if @client.kapso_proxy? && phone_number_id.nil?
+          raise ArgumentError, 'phone_number_id is required when using Kapso proxy'
+        end
+        
+        query_params = {}
+        query_params[:phone_number_id] = phone_number_id if phone_number_id
+        
+        response = @client.request(:delete, media_id, 
+                                   query: query_params, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Download media content
+      def download(media_id:, phone_number_id: nil, headers: {}, 
+                   auth: :auto, as: :binary)
+        # First get the media metadata to get the download URL
+        metadata = get(media_id: media_id, phone_number_id: phone_number_id)
+        download_url = metadata.url
+        
+        # Determine authentication strategy
+        use_auth = case auth
+                   when :auto
+                     # Auto-detect: use auth for graph.facebook.com URLs, no auth for CDNs
+                     download_url.include?('graph.facebook.com')
+                   when :always
+                     true
+                   when :never
+                     false
+                   else
+                     raise ArgumentError, 'auth must be :auto, :always, or :never'
+                   end
+        
+        # Prepare headers
+        download_headers = headers.dup
+        
+        # Make the download request
+        if use_auth
+          response = @client.fetch(download_url, headers: download_headers)
+        else
+          response = @client.raw_request(:get, download_url, headers: download_headers)
+        end
+        
+        unless response.success?
+          raise Errors::GraphApiError.new(
+            message: "Failed to download media: #{response.status}",
+            http_status: response.status,
+            raw_response: response.body
+          )
+        end
+        
+        # Return response based on requested format
+        case as
+        when :binary
+          response.body
+        when :response
+          response
+        when :base64
+          require 'base64'
+          Base64.strict_encode64(response.body)
+        else
+          raise ArgumentError, 'as must be :binary, :response, or :base64'
+        end
+      end
+
+      # Save media to file
+      def save_to_file(media_id:, filepath:, phone_number_id: nil, headers: {}, auth: :auto)
+        content = download(
+          media_id: media_id, 
+          phone_number_id: phone_number_id,
+          headers: headers,
+          auth: auth,
+          as: :binary
+        )
+        
+        File.binwrite(filepath, content)
+        filepath
+      end
+
+      # Get media info including size, type, and download URL
+      def info(media_id:, phone_number_id: nil)
+        metadata = get(media_id: media_id, phone_number_id: phone_number_id)
+        
+        {
+          id: metadata.id,
+          url: metadata.url,
+          mime_type: metadata.mime_type,
+          sha256: metadata.sha256,
+          file_size: metadata.file_size.to_i,
+          messaging_product: metadata.messaging_product
+        }
+      end
+
+      private
+
+      def validate_media_type(type)
+        valid_types = %w[image audio video document sticker]
+        unless valid_types.include?(type.to_s)
+          raise ArgumentError, "Invalid media type '#{type}'. Must be one of: #{valid_types.join(', ')}"
+        end
+      end
+
+      def determine_content_type(file_obj, filename, media_type)
+        # First try to determine from filename
+        if filename
+          mime_types = MIME::Types.type_for(filename)
+          return mime_types.first.content_type unless mime_types.empty?
+        end
+        
+        # Try to determine from file extension if file_obj responds to path
+        if file_obj.respond_to?(:path) && file_obj.path
+          mime_types = MIME::Types.type_for(file_obj.path)
+          return mime_types.first.content_type unless mime_types.empty?
+        end
+        
+        # Fall back to generic types based on media_type
+        case media_type.to_s
+        when 'image'
+          'image/jpeg'
+        when 'audio'
+          'audio/mpeg'
+        when 'video'
+          'video/mp4'
+        when 'document'
+          'application/pdf'
+        when 'sticker'
+          'image/webp'
+        else
+          'application/octet-stream'
+        end
+      end
+    end
+  end
+end

data/lib/whatsapp_cloud_api/resources/messages.rb

@@ -0,0 +1,381 @@
+# frozen_string_literal: true
+
+module WhatsAppCloudApi
+  module Resources
+    class Messages
+      def initialize(client)
+        @client = client
+      end
+
+      # Text Messages
+      def send_text(phone_number_id:, to:, body:, preview_url: nil, context_message_id: nil, 
+                    biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'text',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        payload[:text] = { body: body }
+        payload[:text][:preview_url] = preview_url unless preview_url.nil?
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Image Messages
+      def send_image(phone_number_id:, to:, image:, caption: nil, context_message_id: nil,
+                     biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'image',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        image_obj = build_media_object(image, caption)
+        payload[:image] = image_obj
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Audio Messages  
+      def send_audio(phone_number_id:, to:, audio:, context_message_id: nil,
+                     biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'audio',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        payload[:audio] = build_media_object(audio)
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Document Messages
+      def send_document(phone_number_id:, to:, document:, caption: nil, filename: nil, 
+                        context_message_id: nil, biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'document',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        document_obj = build_media_object(document, caption)
+        document_obj[:filename] = filename if filename
+        payload[:document] = document_obj
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Video Messages
+      def send_video(phone_number_id:, to:, video:, caption: nil, context_message_id: nil,
+                     biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'video',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        payload[:video] = build_media_object(video, caption)
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Sticker Messages
+      def send_sticker(phone_number_id:, to:, sticker:, context_message_id: nil,
+                       biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'sticker',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        payload[:sticker] = build_media_object(sticker)
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Location Messages
+      def send_location(phone_number_id:, to:, latitude:, longitude:, name: nil, 
+                        address: nil, context_message_id: nil, biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'location',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        location_obj = {
+          latitude: latitude,
+          longitude: longitude
+        }
+        location_obj[:name] = name if name
+        location_obj[:address] = address if address
+        
+        payload[:location] = location_obj
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Contact Messages
+      def send_contacts(phone_number_id:, to:, contacts:, context_message_id: nil,
+                        biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'contacts',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        payload[:contacts] = contacts
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Template Messages
+      def send_template(phone_number_id:, to:, name:, language:, components: nil,
+                        context_message_id: nil, biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'template',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        template_obj = {
+          name: name,
+          language: { code: language }
+        }
+        template_obj[:components] = components if components
+        
+        payload[:template] = template_obj
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Reaction Messages
+      def send_reaction(phone_number_id:, to:, message_id:, emoji: nil, 
+                        context_message_id: nil, biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'reaction',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        reaction_obj = { message_id: message_id }
+        reaction_obj[:emoji] = emoji if emoji  # nil emoji removes reaction
+        
+        payload[:reaction] = reaction_obj
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Interactive Button Messages
+      def send_interactive_buttons(phone_number_id:, to:, body_text:, buttons:, 
+                                   header: nil, footer: nil, context_message_id: nil,
+                                   biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'interactive',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        interactive_obj = {
+          type: 'button',
+          body: { text: body_text },
+          action: { buttons: buttons }
+        }
+        
+        interactive_obj[:header] = header if header
+        interactive_obj[:footer] = footer if footer
+        
+        payload[:interactive] = interactive_obj
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Interactive List Messages
+      def send_interactive_list(phone_number_id:, to:, body_text:, button_text:, sections:,
+                                header: nil, footer: nil, context_message_id: nil,
+                                biz_opaque_callback_data: nil)
+        payload = build_base_payload(
+          phone_number_id: phone_number_id,
+          to: to,
+          type: 'interactive',
+          context_message_id: context_message_id,
+          biz_opaque_callback_data: biz_opaque_callback_data
+        )
+        
+        interactive_obj = {
+          type: 'list',
+          body: { text: body_text },
+          action: {
+            button: button_text,
+            sections: sections
+          }
+        }
+        
+        interactive_obj[:header] = header if header
+        interactive_obj[:footer] = footer if footer
+        
+        payload[:interactive] = interactive_obj
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::SendMessageResponse.new(response)
+      end
+
+      # Mark Message as Read
+      def mark_read(phone_number_id:, message_id:)
+        payload = {
+          messaging_product: 'whatsapp',
+          status: 'read',
+          message_id: message_id
+        }
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Send Typing Indicator
+      def send_typing_indicator(phone_number_id:, to:)
+        payload = {
+          messaging_product: 'whatsapp',
+          recipient_type: 'individual',
+          to: to,
+          type: 'text',
+          text: { typing_indicator: { type: 'text' } }
+        }
+        
+        response = @client.request(:post, "#{phone_number_id}/messages", 
+                                   body: payload.to_json, response_type: :json)
+        Types::GraphSuccessResponse.new(response)
+      end
+
+      # Query Message History (Kapso Proxy only)
+      def query(phone_number_id:, direction: nil, status: nil, since: nil, until_time: nil,
+                conversation_id: nil, limit: nil, after: nil, before: nil, fields: nil)
+        assert_kapso_proxy('Message history API')
+        
+        query_params = {
+          phone_number_id: phone_number_id,
+          direction: direction,
+          status: status,
+          since: since,
+          until: until_time,
+          conversation_id: conversation_id,
+          limit: limit,
+          after: after,
+          before: before,
+          fields: fields
+        }.compact
+        
+        response = @client.request(:get, "#{phone_number_id}/messages", 
+                                   query: query_params, response_type: :json)
+        Types::PagedResponse.new(response)
+      end
+
+      # List Messages by Conversation (Kapso Proxy only)
+      def list_by_conversation(phone_number_id:, conversation_id:, limit: nil, 
+                               after: nil, before: nil, fields: nil)
+        query(
+          phone_number_id: phone_number_id,
+          conversation_id: conversation_id,
+          limit: limit,
+          after: after,
+          before: before,
+          fields: fields
+        )
+      end
+
+      private
+
+      def build_base_payload(phone_number_id:, to:, type:, context_message_id: nil, 
+                             biz_opaque_callback_data: nil)
+        payload = {
+          messaging_product: 'whatsapp',
+          recipient_type: 'individual',
+          to: to,
+          type: type
+        }
+        
+        if context_message_id
+          payload[:context] = { message_id: context_message_id }
+        end
+        
+        if biz_opaque_callback_data
+          payload[:biz_opaque_callback_data] = biz_opaque_callback_data
+        end
+        
+        payload
+      end
+
+      def build_media_object(media, caption = nil)
+        media_obj = case media
+                    when Hash
+                      media.dup
+                    when String
+                      # Assume it's either a media ID or URL
+                      if media.match?(/\A\w+\z/) # Simple alphanumeric ID
+                        { id: media }
+                      else
+                        { link: media }
+                      end
+                    else
+                      raise ArgumentError, 'Media must be a Hash, media ID string, or URL string'
+                    end
+        
+        media_obj[:caption] = caption if caption
+        media_obj
+      end
+
+      def assert_kapso_proxy(feature)
+        unless @client.kapso_proxy?
+          raise Errors::KapsoProxyRequiredError.new(feature)
+        end
+      end
+    end
+  end
+end