a2a-ruby 1.0.0

data/lib/a2a/client/api_methods.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module A2A
+  module Client
+    ##
+    # API methods for A2A HTTP client
+    #
+    module ApiMethods
+      ##
+      # Send a message to the agent
+      #
+      # @param message [Message, Hash] The message to send
+      # @param context [Hash, nil] Optional context information
+      # @return [Enumerator, Message] Stream of responses or single response
+      def send_message(message, context: nil)
+        message = ensure_message(message)
+
+        if @config.streaming?
+          send_streaming_message(message, context)
+        else
+          send_sync_message(message, context)
+        end
+      end
+
+      ##
+      # Get a task by ID
+      #
+      # @param task_id [String] The task ID
+      # @param context [Hash, nil] Optional context information
+      # @param history_length [Integer, nil] Maximum number of history messages to include
+      # @return [Task] The task
+      def get_task(task_id, context: nil, history_length: nil)
+        params = { id: task_id }
+        params[:historyLength] = history_length if history_length
+
+        request = build_json_rpc_request("tasks/get", params)
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        ensure_task(response["result"])
+      end
+
+      ##
+      # Cancel a task
+      #
+      # @param task_id [String] The task ID to cancel
+      # @param context [Hash, nil] Optional context information
+      # @return [Task] The updated task
+      def cancel_task(task_id, context: nil)
+        request = build_json_rpc_request("tasks/cancel", { id: task_id })
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        ensure_task(response["result"])
+      end
+
+      ##
+      # Get the agent card
+      #
+      # @param context [Hash, nil] Optional context information
+      # @param authenticated [Boolean] Whether to get authenticated extended card
+      # @return [AgentCard] The agent card
+      def get_card(context: nil, authenticated: false)
+        if authenticated
+          request = build_json_rpc_request("agent/getAuthenticatedExtendedCard", {})
+          response = execute_with_middleware(request, context || {}) do |req, _ctx|
+            send_json_rpc_request(req)
+          end
+          ensure_agent_card(response["result"])
+        else
+          # Use HTTP GET for basic agent card
+          response = execute_with_middleware({}, context || {}) do |_req, _ctx|
+            @connection.get("/agent-card") do |request|
+              request.headers.merge!(@config.all_headers)
+            end
+          end
+
+          raise A2A::Errors::HTTPError, "HTTP #{response.status}: #{response.body}" unless response.success?
+
+          ensure_agent_card(JSON.parse(response.body))
+
+        end
+      end
+
+      ##
+      # Resubscribe to a task
+      #
+      # @param task_id [String] The task ID to resubscribe to
+      # @param context [Hash, nil] Optional context information
+      # @return [Task] The task
+      def resubscribe(task_id, context: nil)
+        request = build_json_rpc_request("tasks/resubscribe", { id: task_id })
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        ensure_task(response["result"])
+      end
+
+      ##
+      # Set a task callback (deprecated - use set_task_push_notification_config)
+      #
+      # @param task_id [String] The task ID
+      # @param push_notification_config [Hash] The push notification configuration
+      # @param context [Hash, nil] Optional context information
+      # @return [Hash] The response
+      def set_task_callback(task_id, push_notification_config, context: nil)
+        params = {
+          taskId: task_id,
+          pushNotificationConfig: push_notification_config
+        }
+
+        request = build_json_rpc_request("tasks/pushNotificationConfig/set", params)
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        response["result"]
+      end
+
+      ##
+      # Get a task callback (deprecated - use get_task_push_notification_config)
+      #
+      # @param task_id [String] The task ID
+      # @param push_notification_config_id [String] The config ID
+      # @param context [Hash, nil] Optional context information
+      # @return [Hash] The configuration
+      def get_task_callback(task_id, push_notification_config_id, context: nil)
+        params = {
+          taskId: task_id,
+          pushNotificationConfigId: push_notification_config_id
+        }
+
+        request = build_json_rpc_request("tasks/pushNotificationConfig/get", params)
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        response["result"]
+      end
+
+      ##
+      # List task callbacks (deprecated - use list_task_push_notification_configs)
+      #
+      # @param task_id [String] The task ID
+      # @param context [Hash, nil] Optional context information
+      # @return [Array] List of configurations
+      def list_task_callbacks(task_id, context: nil)
+        params = { taskId: task_id }
+
+        request = build_json_rpc_request("tasks/pushNotificationConfig/list", params)
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        response["result"]
+      end
+
+      ##
+      # Delete a task callback (deprecated - use delete_task_push_notification_config)
+      #
+      # @param task_id [String] The task ID
+      # @param push_notification_config_id [String] The config ID
+      # @param context [Hash, nil] Optional context information
+      # @return [Boolean] Success status
+      def delete_task_callback(task_id, push_notification_config_id, context: nil)
+        params = {
+          taskId: task_id,
+          pushNotificationConfigId: push_notification_config_id
+        }
+
+        request = build_json_rpc_request("tasks/pushNotificationConfig/delete", params)
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        response["result"]
+      end
+
+      ##
+      # Set a push notification config for a task
+      #
+      # @param task_id [String] The task ID
+      # @param config [Hash] The push notification configuration
+      # @param context [Hash, nil] Optional context information
+      # @return [Hash] The response
+      def set_task_push_notification_config(task_id, config, context: nil)
+        params = {
+          taskId: task_id,
+          pushNotificationConfig: config
+        }
+
+        request = build_json_rpc_request("tasks/pushNotificationConfig/set", params)
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        response["result"]
+      end
+
+      ##
+      # Get a push notification config for a task
+      #
+      # @param task_id [String] The task ID
+      # @param config_id [String] The config ID
+      # @param context [Hash, nil] Optional context information
+      # @return [Hash] The configuration
+      def get_task_push_notification_config(task_id, config_id, context: nil)
+        params = {
+          taskId: task_id,
+          pushNotificationConfigId: config_id
+        }
+
+        request = build_json_rpc_request("tasks/pushNotificationConfig/get", params)
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        response["result"]
+      end
+
+      ##
+      # List push notification configs for a task
+      #
+      # @param task_id [String] The task ID
+      # @param context [Hash, nil] Optional context information
+      # @return [Array] List of configurations
+      def list_task_push_notification_configs(task_id, context: nil)
+        params = { taskId: task_id }
+
+        request = build_json_rpc_request("tasks/pushNotificationConfig/list", params)
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        response["result"]
+      end
+
+      ##
+      # Delete a push notification config for a task
+      #
+      # @param task_id [String] The task ID
+      # @param config_id [String] The config ID
+      # @param context [Hash, nil] Optional context information
+      # @return [Boolean] Success status
+      def delete_task_push_notification_config(task_id, config_id, context: nil)
+        params = {
+          taskId: task_id,
+          pushNotificationConfigId: config_id
+        }
+
+        request = build_json_rpc_request("tasks/pushNotificationConfig/delete", params)
+        response = execute_with_middleware(request, context || {}) do |req, _ctx|
+          send_json_rpc_request(req)
+        end
+
+        response["result"]
+      end
+    end
+  end
+end

data/lib/a2a/client/auth/api_key.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+##
+# API Key authentication strategy
+#
+# Supports API key authentication via headers, query parameters,
+# or custom locations as specified by the agent's security scheme.
+#
+module A2A
+  module Client
+    module Auth
+      class ApiKey
+        attr_reader :key, :value, :location, :name
+
+        # Valid locations for API key
+        VALID_LOCATIONS = %w[header query cookie].freeze
+
+        ##
+        # Initialize API key authentication
+        #
+        # @param key [String] The API key value
+        # @param name [String] The parameter/header name for the API key (default: 'X-API-Key')
+        # @param location [String] Where to place the API key: 'header', 'query', or 'cookie' (default: 'header')
+        def initialize(key:, name: "X-API-Key", location: "header")
+          @key = key
+          @name = name
+          @location = location.downcase
+          @value = key # Alias for consistency
+
+          validate_configuration!
+        end
+
+        ##
+        # Apply authentication to a Faraday request
+        #
+        # @param request [Faraday::Request] The request to authenticate
+        def apply_to_request(request)
+          case @location
+          when "header"
+            request.headers[@name] = @key
+          when "query"
+            # Add to query parameters
+            request.params[@name] = @key
+          when "cookie"
+            # Add to cookie header
+            existing_cookies = request.headers["Cookie"]
+            cookie_value = "#{@name}=#{@key}"
+
+            request.headers["Cookie"] = if existing_cookies
+                                          "#{existing_cookies}; #{cookie_value}"
+                                        else
+                                          cookie_value
+                                        end
+          end
+        end
+
+        ##
+        # Get the authentication header (for header-based API keys)
+        #
+        # @return [Hash] Header name and value
+        def authentication_header
+          return {} unless @location == "header"
+
+          { @name => @key }
+        end
+
+        ##
+        # Get the authentication query parameter (for query-based API keys)
+        #
+        # @return [Hash] Parameter name and value
+        def authentication_params
+          return {} unless @location == "query"
+
+          { @name => @key }
+        end
+
+        ##
+        # Check if the API key is valid (basic validation)
+        #
+        # @return [Boolean] True if key appears valid
+        def valid?
+          @key.present? && @key.is_a?(String)
+        end
+
+        ##
+        # Mask the API key for logging (shows only first and last 4 characters)
+        #
+        # @return [String] Masked API key
+        def masked_key
+          return "[empty]" if @key.nil? || (respond_to?(:empty?) && empty?) || (is_a?(String) && strip.empty?)
+          return @key if @key.length <= 8
+
+          "#{@key[0..3]}#{'*' * (@key.length - 8)}#{@key[-4..]}"
+        end
+
+        ##
+        # Create API key authentication from security scheme
+        #
+        # @param scheme [Hash] Security scheme definition
+        # @param key_value [String] The API key value
+        # @return [ApiKey] Configured API key authentication
+        def self.from_security_scheme(scheme, key_value)
+          location = scheme["in"] || "header"
+          name = scheme["name"] || "X-API-Key"
+
+          new(key: key_value, name: name, location: location)
+        end
+
+        ##
+        # Convert to hash representation
+        #
+        # @return [Hash] Configuration as hash
+        def to_h
+          {
+            type: "api_key",
+            key: masked_key,
+            name: @name,
+            location: @location
+          }
+        end
+
+        ##
+        # String representation (with masked key)
+        #
+        # @return [String] String representation
+        def to_s
+          "ApiKey(name=#{@name}, location=#{@location}, key=#{masked_key})"
+        end
+
+        ##
+        # Inspect representation (with masked key)
+        #
+        # @return [String] Inspect representation
+        def inspect
+          "#<A2A::Client::Auth::ApiKey:0x#{object_id.to_s(16)} #{self}>"
+        end
+
+        private
+
+        ##
+        # Validate the authentication configuration
+        def validate_configuration!
+          if @key.nil? || (respond_to?(:empty?) && empty?) || (is_a?(String) && strip.empty?)
+            raise ArgumentError,
+                  "API key cannot be nil or empty"
+          end
+          raise ArgumentError, "API key must be a string" unless @key.is_a?(String)
+
+          if @name.nil? || (respond_to?(:empty?) && empty?) || (is_a?(String) && strip.empty?)
+            raise ArgumentError,
+                  "Name cannot be nil or empty"
+          end
+
+          return if VALID_LOCATIONS.include?(@location)
+
+          raise ArgumentError, "Invalid location '#{@location}'. Must be one of: #{VALID_LOCATIONS.join(', ')}"
+        end
+      end
+    end
+  end
+end