a2a-ruby 1.0.0

data/lib/a2a/types/part.rb

@@ -0,0 +1,288 @@
+# frozen_string_literal: true
+
+module A2A
+  module Types
+    ##
+    # Base class for message parts (discriminated union)
+    #
+    # Parts represent different types of content within a message.
+    # This is an abstract base class - use TextPart, FilePart, or DataPart.
+    #
+    class Part < A2A::Types::BaseModel
+      attr_reader :kind, :metadata
+
+      ##
+      # Create a part from a hash (factory method)
+      #
+      # @param hash [Hash] The hash representation
+      # @return [Part] The appropriate part subclass instance
+      def self.from_h(hash)
+        return hash if hash.is_a?(Part) # Already a Part instance
+        return nil if hash.nil?
+
+        kind = hash[:kind] || hash["kind"]
+        case kind
+        when PART_KIND_TEXT
+          TextPart.from_h(hash)
+        when PART_KIND_FILE
+          FilePart.from_h(hash)
+        when PART_KIND_DATA
+          DataPart.from_h(hash)
+        else
+          raise ArgumentError, "Unknown part kind: #{kind}"
+        end
+      end
+
+      protected
+
+      def initialize(kind:, metadata: nil)
+        @kind = kind
+        @metadata = metadata
+        validate!
+      end
+
+      private
+
+      def validate!
+        validate_required(:kind)
+        validate_inclusion(:kind, VALID_PART_KINDS)
+      end
+    end
+
+    ##
+    # Represents a text part in a message
+    #
+    class TextPart < Part
+      attr_reader :text
+
+      ##
+      # Initialize a new text part
+      #
+      # @param text [String] The text content
+      # @param metadata [Hash, nil] Additional metadata
+      def initialize(text:, metadata: nil)
+        @text = text
+        super(kind: PART_KIND_TEXT, metadata: metadata)
+      end
+
+      ##
+      # Create a TextPart from a hash
+      #
+      # @param hash [Hash] The hash representation
+      # @return [TextPart] The new instance
+      def self.from_h(hash)
+        return hash if hash.is_a?(TextPart)
+        return nil if hash.nil?
+
+        # Convert string keys to symbols and snake_case camelCase keys
+        normalized_hash = {}
+        hash.each do |key, value|
+          snake_key = BaseModel.underscore(key.to_s).to_sym
+          normalized_hash[snake_key] = value unless snake_key == :kind
+        end
+
+        new(**normalized_hash)
+      end
+
+      private
+
+      def validate!
+        super
+        validate_required(:text)
+        validate_type(:text, String)
+      end
+    end
+
+    ##
+    # Represents a file part in a message
+    #
+    class FilePart < Part
+      attr_reader :file
+
+      ##
+      # Initialize a new file part
+      #
+      # @param file [FileBase] The file object
+      # @param metadata [Hash, nil] Additional metadata
+      def initialize(file:, metadata: nil)
+        @file = file.is_a?(Hash) ? FileBase.from_h(file) : file
+        super(kind: PART_KIND_FILE, metadata: metadata)
+      end
+
+      ##
+      # Create a FilePart from a hash
+      #
+      # @param hash [Hash] The hash representation
+      # @return [FilePart] The new instance
+      def self.from_h(hash)
+        return hash if hash.is_a?(FilePart)
+        return nil if hash.nil?
+
+        # Convert string keys to symbols and snake_case camelCase keys
+        normalized_hash = {}
+        hash.each do |key, value|
+          snake_key = BaseModel.underscore(key.to_s).to_sym
+          normalized_hash[snake_key] = value unless snake_key == :kind
+        end
+
+        new(**normalized_hash)
+      end
+
+      private
+
+      def validate!
+        super
+        validate_required(:file)
+        validate_type(:file, FileBase)
+      end
+    end
+
+    ##
+    # Represents a data part in a message
+    #
+    class DataPart < Part
+      attr_reader :data
+
+      ##
+      # Initialize a new data part
+      #
+      # @param data [Object] The data content (any JSON-serializable object)
+      # @param metadata [Hash, nil] Additional metadata
+      def initialize(data:, metadata: nil)
+        @data = data
+        super(kind: PART_KIND_DATA, metadata: metadata)
+      end
+
+      ##
+      # Create a DataPart from a hash
+      #
+      # @param hash [Hash] The hash representation
+      # @return [DataPart] The new instance
+      def self.from_h(hash)
+        return hash if hash.is_a?(DataPart)
+        return nil if hash.nil?
+
+        # Convert string keys to symbols and snake_case camelCase keys
+        normalized_hash = {}
+        hash.each do |key, value|
+          snake_key = BaseModel.underscore(key.to_s).to_sym
+          normalized_hash[snake_key] = value unless snake_key == :kind
+        end
+
+        new(**normalized_hash)
+      end
+
+      private
+
+      def validate!
+        super
+        validate_required(:data)
+      end
+    end
+
+    ##
+    # Base class for file representations
+    #
+    class FileBase < A2A::Types::BaseModel
+      ##
+      # Create a file from a hash (factory method)
+      #
+      # @param hash [Hash] The hash representation
+      # @return [FileBase] The appropriate file subclass instance
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        if hash.key?(:bytes) || hash.key?("bytes")
+          FileWithBytes.from_h(hash)
+        elsif hash.key?(:uri) || hash.key?("uri")
+          FileWithUri.from_h(hash)
+        else
+          raise ArgumentError, "File must have either 'bytes' or 'uri'"
+        end
+      end
+    end
+
+    ##
+    # Represents a file with base64-encoded bytes
+    #
+    class FileWithBytes < FileBase
+      attr_reader :name, :mime_type, :bytes
+
+      ##
+      # Initialize a new file with bytes
+      #
+      # @param name [String] The file name
+      # @param mime_type [String] The MIME type
+      # @param bytes [String] Base64-encoded file content
+      def initialize(name:, mime_type:, bytes:)
+        @name = name
+        @mime_type = mime_type
+        @bytes = bytes
+        validate!
+      end
+
+      ##
+      # Get the decoded file content
+      #
+      # @return [String] The decoded binary content
+      def content
+        require "base64"
+        Base64.decode64(@bytes)
+      end
+
+      ##
+      # Get the file size in bytes
+      #
+      # @return [Integer] The file size
+      def size
+        content.bytesize
+      end
+
+      private
+
+      def validate!
+        validate_required(:name, :mime_type, :bytes)
+        validate_type(:name, String)
+        validate_type(:mime_type, String)
+        validate_type(:bytes, String)
+      end
+    end
+
+    ##
+    # Represents a file with a URI reference
+    #
+    class FileWithUri < FileBase
+      attr_reader :name, :mime_type, :uri
+
+      ##
+      # Initialize a new file with URI
+      #
+      # @param name [String] The file name
+      # @param mime_type [String] The MIME type
+      # @param uri [String] The file URI
+      def initialize(name:, mime_type:, uri:)
+        @name = name
+        @mime_type = mime_type
+        @uri = uri
+        validate!
+      end
+
+      private
+
+      def validate!
+        validate_required(:name, :mime_type, :uri)
+        validate_type(:name, String)
+        validate_type(:mime_type, String)
+        validate_type(:uri, String)
+
+        # Basic URI validation
+        begin
+          require "uri"
+          URI.parse(@uri)
+        rescue URI::InvalidURIError
+          raise ArgumentError, "Invalid URI: #{@uri}"
+        end
+      end
+    end
+  end
+end

data/lib/a2a/types/push_notification.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module A2A
+  module Types
+    ##
+    # Represents a push notification configuration
+    #
+    # Push notification configs define how and where to send notifications
+    # about task updates and other events.
+    #
+    class PushNotificationConfig < A2A::Types::BaseModel
+      attr_reader :id, :url, :token, :authentication
+
+      ##
+      # Initialize a new push notification config
+      #
+      # @param url [String] The webhook URL
+      # @param id [String, nil] Optional config identifier
+      # @param token [String, nil] Optional authentication token
+      # @param authentication [Hash, nil] Authentication configuration
+      def initialize(url:, id: nil, token: nil, authentication: nil)
+        @url = url
+        @id = id
+        @token = token
+        @authentication = authentication
+
+        validate!
+      end
+
+      ##
+      # Check if authentication is configured
+      #
+      # @return [Boolean] True if authentication is present
+      def authenticated?
+        !@token.nil? || !@authentication.nil?
+      end
+
+      ##
+      # Get authentication headers for webhook requests
+      #
+      # @return [Hash] Headers to include in webhook requests
+      def auth_headers
+        headers = {}
+
+        headers["Authorization"] = "Bearer #{@token}" if @token
+
+        if @authentication.is_a?(Hash)
+          case @authentication["type"]
+          when "bearer"
+            headers["Authorization"] = "Bearer #{@authentication['token']}"
+          when "basic"
+            require "base64"
+            credentials = Base64.strict_encode64("#{@authentication['username']}:#{@authentication['password']}")
+            headers["Authorization"] = "Basic #{credentials}"
+          when "api_key"
+            key_name = @authentication["key_name"] || "X-API-Key"
+            headers[key_name] = @authentication["api_key"]
+          end
+        end
+
+        headers
+      end
+
+      private
+
+      def validate!
+        validate_required(:url)
+        validate_type(:url, String)
+
+        # Basic URL validation
+        begin
+          require "uri"
+          uri = URI.parse(@url)
+          raise ArgumentError, "URL must be HTTP or HTTPS" unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+        rescue URI::InvalidURIError
+          raise ArgumentError, "Invalid URL: #{@url}"
+        end
+      end
+    end
+
+    ##
+    # Represents a task-specific push notification configuration
+    #
+    # Links a task to a push notification configuration for receiving
+    # updates about that specific task.
+    #
+    class TaskPushNotificationConfig < A2A::Types::BaseModel
+      attr_reader :task_id, :push_notification_config
+
+      ##
+      # Initialize a new task push notification config
+      #
+      # @param task_id [String] The task identifier
+      # @param push_notification_config [PushNotificationConfig, Hash] The notification config
+      def initialize(task_id:, push_notification_config:)
+        @task_id = task_id
+        @push_notification_config = if push_notification_config.is_a?(PushNotificationConfig)
+                                      push_notification_config
+                                    else
+                                      PushNotificationConfig.from_h(push_notification_config)
+                                    end
+
+        validate!
+      end
+
+      ##
+      # Get the webhook URL
+      #
+      # @return [String] The webhook URL
+      def webhook_url
+        @push_notification_config.url
+      end
+
+      ##
+      # Get authentication headers
+      #
+      # @return [Hash] Authentication headers
+      def auth_headers
+        @push_notification_config.auth_headers
+      end
+
+      ##
+      # Check if authentication is configured
+      #
+      # @return [Boolean] True if authentication is present
+      def authenticated?
+        @push_notification_config.authenticated?
+      end
+
+      private
+
+      def validate!
+        validate_required(:task_id, :push_notification_config)
+        validate_type(:task_id, String)
+        validate_type(:push_notification_config, PushNotificationConfig)
+      end
+    end
+  end
+end

data/lib/a2a/types/security.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module A2A
+  module Types
+    ##
+    # Base class for security schemes (discriminated union)
+    #
+    # Security schemes define how authentication and authorization
+    # should be handled for agent interactions.
+    #
+    class SecurityScheme < A2A::Types::BaseModel
+      attr_reader :type
+
+      ##
+      # Create a security scheme from a hash (factory method)
+      #
+      # @param hash [Hash] The hash representation
+      # @return [SecurityScheme] The appropriate security scheme subclass instance
+      def self.from_h(hash)
+        return nil if hash.nil?
+
+        type = hash[:type] || hash["type"]
+        case type
+        when SECURITY_TYPE_API_KEY
+          ApiKeySecurityScheme.from_h(hash)
+        when SECURITY_TYPE_HTTP
+          HttpSecurityScheme.from_h(hash)
+        when SECURITY_TYPE_OAUTH2
+          OAuth2SecurityScheme.from_h(hash)
+        when SECURITY_TYPE_OPENID_CONNECT
+          OpenIdConnectSecurityScheme.from_h(hash)
+        when SECURITY_TYPE_MUTUAL_TLS
+          MutualTlsSecurityScheme.from_h(hash)
+        else
+          raise ArgumentError, "Unknown security scheme type: #{type}"
+        end
+      end
+
+      protected
+
+      def initialize(type:)
+        @type = type
+        validate!
+      end
+
+      private
+
+      def validate!
+        validate_required(:type)
+        validate_inclusion(:type, VALID_SECURITY_TYPES)
+      end
+    end
+
+    ##
+    # API Key security scheme
+    #
+    class ApiKeySecurityScheme < SecurityScheme
+      attr_reader :name, :location
+
+      ##
+      # Initialize a new API key security scheme
+      #
+      # @param name [String] The name of the API key parameter
+      # @param location [String] Where the API key is sent ("query", "header", "cookie")
+      def initialize(name:, location:)
+        @name = name
+        @location = location
+        super(type: SECURITY_TYPE_API_KEY)
+      end
+
+      private
+
+      def validate!
+        super
+        validate_required(:name, :location)
+        validate_inclusion(:location, %w[query header cookie])
+      end
+    end
+
+    ##
+    # HTTP security scheme (Basic, Bearer, etc.)
+    #
+    class HttpSecurityScheme < SecurityScheme
+      attr_reader :scheme, :bearer_format
+
+      ##
+      # Initialize a new HTTP security scheme
+      #
+      # @param scheme [String] The HTTP authentication scheme ("basic", "bearer", etc.)
+      # @param bearer_format [String, nil] Format of bearer token (e.g., "JWT")
+      def initialize(scheme:, bearer_format: nil)
+        @scheme = scheme
+        @bearer_format = bearer_format
+        super(type: SECURITY_TYPE_HTTP)
+      end
+
+      private
+
+      def validate!
+        super
+        validate_required(:scheme)
+        validate_inclusion(:scheme, %w[basic bearer digest])
+      end
+    end
+
+    ##
+    # OAuth 2.0 security scheme
+    #
+    class OAuth2SecurityScheme < SecurityScheme
+      attr_reader :flows, :scopes
+
+      ##
+      # Initialize a new OAuth 2.0 security scheme
+      #
+      # @param flows [Hash] OAuth 2.0 flows configuration
+      # @param scopes [Hash, nil] Available scopes
+      def initialize(flows:, scopes: nil)
+        @flows = flows
+        @scopes = scopes
+        super(type: SECURITY_TYPE_OAUTH2)
+      end
+
+      private
+
+      def validate!
+        super
+        validate_required(:flows)
+        validate_type(:flows, Hash)
+      end
+    end
+
+    ##
+    # OpenID Connect security scheme
+    #
+    class OpenIdConnectSecurityScheme < SecurityScheme
+      attr_reader :open_id_connect_url
+
+      ##
+      # Initialize a new OpenID Connect security scheme
+      #
+      # @param open_id_connect_url [String] The OpenID Connect discovery URL
+      def initialize(open_id_connect_url:)
+        @open_id_connect_url = open_id_connect_url
+        super(type: SECURITY_TYPE_OPENID_CONNECT)
+      end
+
+      private
+
+      def validate!
+        super
+        validate_required(:open_id_connect_url)
+        validate_type(:open_id_connect_url, String)
+      end
+    end
+
+    ##
+    # Mutual TLS security scheme
+    #
+    class MutualTlsSecurityScheme < SecurityScheme
+      ##
+      # Initialize a new mutual TLS security scheme
+      def initialize
+        super(type: SECURITY_TYPE_MUTUAL_TLS)
+      end
+    end
+  end
+end