attio-ruby 0.1.0

data/lib/attio/util/configuration.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module Attio
+  # Utility classes for the Attio gem
+  module Util
+    # Configuration management for the Attio gem
+    class Configuration
+      # Raised when configuration validation fails
+      class ConfigurationError < ::Attio::InvalidRequestError; end
+
+      # Settings that must be configured
+      REQUIRED_SETTINGS = %i[api_key].freeze
+      # Optional settings with defaults
+      OPTIONAL_SETTINGS = %i[
+        api_base
+        api_version
+        timeout
+        open_timeout
+        max_retries
+        logger
+        debug
+        ca_bundle_path
+        verify_ssl_certs
+        use_faraday
+      ].freeze
+
+      # All available configuration settings
+      ALL_SETTINGS = (REQUIRED_SETTINGS + OPTIONAL_SETTINGS).freeze
+
+      # Default values for optional settings
+      DEFAULT_SETTINGS = {
+        api_base: "https://api.attio.com",
+        api_version: "v2",
+        timeout: 30,
+        open_timeout: 10,
+        max_retries: 3,
+        logger: nil,
+        debug: false,
+        ca_bundle_path: nil,
+        verify_ssl_certs: true,
+        use_faraday: true
+      }.freeze
+
+      attr_reader(*ALL_SETTINGS)
+
+      def initialize
+        @mutex = Mutex.new
+        @configured = false
+        reset_without_lock!
+      end
+
+      # Reset configuration to defaults
+      # @return [void]
+      def reset!
+        @mutex.synchronize do
+          reset_without_lock!
+          @configured = false
+        end
+      end
+
+      def configure
+        raise ConfigurationError, "Configuration has already been finalized" if frozen?
+
+        @mutex.synchronize do
+          yield(self) if block_given?
+          validate!
+          @configured = true
+        end
+      end
+
+      # Call this to make configuration immutable
+      def finalize!
+        @mutex.synchronize do
+          validate!
+          freeze unless frozen?
+        end
+      end
+
+      def validate!
+        REQUIRED_SETTINGS.each do |setting|
+          value = instance_variable_get("@#{setting}")
+          if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+            raise ConfigurationError, "#{setting} must be configured"
+          end
+        end
+
+        raise ConfigurationError, "timeout must be positive" if @timeout && @timeout <= 0
+        raise ConfigurationError, "open_timeout must be positive" if @open_timeout && @open_timeout <= 0
+        raise ConfigurationError, "max_retries must be non-negative" if @max_retries&.negative?
+
+        true
+      end
+
+      # Convert configuration to hash
+      # @return [Hash] Configuration settings as a hash
+      def to_h
+        ALL_SETTINGS.each_with_object({}) do |setting, hash|
+          hash[setting] = instance_variable_get("@#{setting}")
+        end
+      end
+
+      def apply_env_vars!
+        raise ConfigurationError, "Cannot modify frozen configuration" if frozen?
+
+        @mutex.synchronize do
+          @api_key = ENV.fetch("ATTIO_API_KEY", @api_key)
+          @api_base = ENV.fetch("ATTIO_API_BASE", @api_base)
+          @api_version = ENV.fetch("ATTIO_API_VERSION", @api_version)
+          @timeout = ENV.fetch("ATTIO_TIMEOUT", @timeout).to_i if ENV.key?("ATTIO_TIMEOUT")
+          @open_timeout = ENV.fetch("ATTIO_OPEN_TIMEOUT", @open_timeout).to_i if ENV.key?("ATTIO_OPEN_TIMEOUT")
+          @max_retries = ENV.fetch("ATTIO_MAX_RETRIES", @max_retries).to_i if ENV.key?("ATTIO_MAX_RETRIES")
+          @debug = ENV.fetch("ATTIO_DEBUG", @debug).to_s.downcase == "true" if ENV.key?("ATTIO_DEBUG")
+          @ca_bundle_path = ENV.fetch("ATTIO_CA_BUNDLE_PATH", @ca_bundle_path) if ENV.key?("ATTIO_CA_BUNDLE_PATH")
+          @verify_ssl_certs = ENV.fetch("ATTIO_VERIFY_SSL_CERTS", @verify_ssl_certs).to_s.downcase != "false" if ENV.key?("ATTIO_VERIFY_SSL_CERTS")
+          @use_faraday = ENV.fetch("ATTIO_USE_FARADAY", @use_faraday).to_s.downcase != "false" if ENV.key?("ATTIO_USE_FARADAY")
+
+          if ENV.key?("ATTIO_LOGGER")
+            logger_class = ENV["ATTIO_LOGGER"]
+            @logger = (logger_class == "STDOUT") ? Logger.new($stdout) : nil
+          end
+        end
+      end
+
+      # Create a new configuration with merged options
+      # @param options [Hash] Options to merge
+      # @return [Configuration] New configuration instance
+      def merge(options)
+        dup.tap do |config|
+          options.each do |key, value|
+            if ALL_SETTINGS.include?(key.to_sym)
+              config.instance_variable_set("@#{key}", value)
+            end
+          end
+        end
+      end
+
+      # Create a duplicate configuration
+      # @return [Configuration] Duplicate configuration instance
+      def dup
+        self.class.new.tap do |config|
+          ALL_SETTINGS.each do |setting|
+            config.instance_variable_set("@#{setting}", instance_variable_get("@#{setting}"))
+          end
+        end
+      end
+
+      # Setters - only work before configuration is frozen
+      ALL_SETTINGS.each do |setting|
+        define_method("#{setting}=") do |value|
+          raise ConfigurationError, "Cannot modify frozen configuration" if frozen?
+          # Don't synchronize here - it's already synchronized in configure
+          instance_variable_set("@#{setting}", value)
+        end
+      end
+
+      private
+
+      def reset_without_lock!
+        DEFAULT_SETTINGS.each do |key, value|
+          instance_variable_set("@#{key}", value)
+        end
+        @api_key = nil
+      end
+    end
+  end
+end

data/lib/attio/util/id_extractor.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Attio
+  module Util
+    # Centralized ID extraction utility for handling various ID formats
+    # across different Attio resources
+    class IdExtractor
+      class << self
+        # Extract an ID from various formats
+        # @param id [String, Hash, nil] The ID in various formats
+        # @param key [Symbol, String] The key to extract from a hash ID
+        # @return [String, nil] The extracted ID
+        def extract(id, key = nil)
+          return nil if id.nil?
+
+          case id
+          when String
+            id
+          when Hash
+            extract_from_hash(id, key)
+          else
+            id.to_s if id.respond_to?(:to_s)
+          end
+        end
+
+        # Extract a specific ID type from a potentially nested structure
+        # @param id [String, Hash, nil] The ID structure
+        # @param resource_type [Symbol] The resource type (:record, :webhook, :attribute, etc.)
+        # @return [String, nil] The extracted ID
+        def extract_for_resource(id, resource_type)
+          return nil if id.nil?
+
+          key = resource_key_map[resource_type]
+          return id if id.is_a?(String) && key.nil?
+
+          extract(id, key)
+        end
+
+        # Normalize an ID structure to a consistent format
+        # @param id [String, Hash, nil] The ID to normalize
+        # @param resource_type [Symbol] The resource type
+        # @return [Hash, String, nil] The normalized ID
+        def normalize(id, resource_type)
+          return nil if id.nil?
+
+          extracted = extract_for_resource(id, resource_type)
+          return nil if extracted.nil?
+
+          # For resources that need hash format
+          if hash_format_resources.include?(resource_type)
+            key = resource_key_map[resource_type]
+            key ? {key => extracted} : extracted
+          else
+            extracted
+          end
+        end
+
+        private
+
+        def extract_from_hash(hash, key = nil)
+          return nil unless hash.is_a?(Hash)
+
+          if key
+            # Try both symbol and string keys
+            hash[key] || hash[key.to_s] || hash[key.to_sym]
+          else
+            # Try common ID keys in order of preference
+            common_keys.each do |k|
+              value = hash[k] || hash[k.to_s]
+              return value if value
+            end
+            nil
+          end
+        end
+
+        def resource_key_map
+          @resource_key_map ||= {
+            record: :record_id,
+            workspace_member: :workspace_member_id,
+            webhook: :webhook_id,
+            attribute: :attribute_id,
+            object: :object_id,
+            list: :list_id,
+            note: :note_id,
+            comment: :comment_id,
+            task: :task_id,
+            entry: :entry_id,
+            thread: :thread_id
+          }.freeze
+        end
+
+        def hash_format_resources
+          @hash_format_resources ||= %i[record].freeze
+        end
+
+        def common_keys
+          @common_keys ||= %i[
+            id
+            record_id
+            workspace_member_id
+            webhook_id
+            attribute_id
+            object_id
+            list_id
+            note_id
+            comment_id
+            task_id
+            entry_id
+            thread_id
+          ].freeze
+        end
+      end
+    end
+  end
+end

data/lib/attio/util/webhook_signature.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "time"
+
+module Attio
+  module Util
+    # Verifies webhook signatures from Attio to ensure authenticity
+    class WebhookSignature
+      # HTTP header containing the webhook signature
+      SIGNATURE_HEADER = "x-attio-signature"
+      # HTTP header containing the request timestamp
+      TIMESTAMP_HEADER = "x-attio-timestamp"
+      TOLERANCE_SECONDS = 300 # 5 minutes
+
+      class << self
+        # Verify webhook signature (raises exception on failure)
+        def verify!(payload:, signature:, timestamp:, secret:, tolerance: TOLERANCE_SECONDS)
+          validate_inputs!(payload, signature, timestamp, secret)
+
+          # Check timestamp to prevent replay attacks
+          verify_timestamp!(timestamp, tolerance)
+
+          # Calculate expected signature
+          expected_signature = calculate_signature(payload, timestamp, secret)
+
+          # Constant-time comparison to prevent timing attacks
+          raise SignatureVerificationError, "Invalid signature" unless secure_compare(signature, expected_signature)
+        rescue => e
+          raise SignatureVerificationError, "Webhook signature verification failed: #{e.message}"
+        end
+
+        # Verify webhook signature (returns boolean)
+        def verify(payload:, signature:, timestamp:, secret:, tolerance: TOLERANCE_SECONDS)
+          verify!(payload: payload, signature: signature, timestamp: timestamp, secret: secret, tolerance: tolerance)
+          true
+        rescue SignatureVerificationError
+          false
+        end
+
+        # Calculate signature for a payload
+        def calculate_signature(payload, timestamp, secret)
+          # Ensure payload is a string
+          payload_string = payload.is_a?(String) ? payload : JSON.generate(payload)
+
+          # Create the signed payload
+          signed_payload = "#{timestamp}.#{payload_string}"
+
+          # Calculate HMAC
+          hmac = OpenSSL::HMAC.hexdigest("SHA256", secret, signed_payload)
+
+          # Return in the format Attio uses
+          "v1=#{hmac}"
+        end
+
+        # Extract signature from headers
+        def extract_from_headers(headers)
+          signature = headers[SIGNATURE_HEADER] || headers[SIGNATURE_HEADER.upcase] || headers[SIGNATURE_HEADER.tr("-", "_").upcase]
+          timestamp = headers[TIMESTAMP_HEADER] || headers[TIMESTAMP_HEADER.upcase] || headers[TIMESTAMP_HEADER.tr("-", "_").upcase]
+
+          raise SignatureVerificationError, "Missing signature header: #{SIGNATURE_HEADER}" unless signature
+          raise SignatureVerificationError, "Missing timestamp header: #{TIMESTAMP_HEADER}" unless timestamp
+
+          {
+            signature: signature,
+            timestamp: timestamp
+          }
+        end
+
+        private
+
+        def validate_inputs!(payload, signature, timestamp, secret)
+          raise ArgumentError, "Payload cannot be nil" if payload.nil?
+          raise ArgumentError, "Signature cannot be nil or empty" if signature.nil? || signature.empty?
+          raise ArgumentError, "Timestamp cannot be nil or empty" if timestamp.nil? || timestamp.to_s.empty?
+          raise ArgumentError, "Secret cannot be nil or empty" if secret.nil? || secret.empty?
+        end
+
+        def verify_timestamp!(timestamp, tolerance)
+          timestamp_int = timestamp.to_i
+          current_time = Time.now.to_i
+
+          if timestamp_int < (current_time - tolerance)
+            raise SignatureVerificationError, "Timestamp too old"
+          end
+
+          if timestamp_int > (current_time + tolerance)
+            raise SignatureVerificationError, "Timestamp too far in the future"
+          end
+        end
+
+        def secure_compare(a, b)
+          return false unless a.bytesize == b.bytesize
+
+          # Use constant-time comparison
+          res = 0
+          a.bytes.zip(b.bytes) { |x, y| res |= x ^ y }
+          res == 0
+        end
+      end
+
+      # Helper class for webhook handlers
+      class Handler
+        attr_reader :secret
+
+        def initialize(secret)
+          @secret = secret
+          validate_secret!
+        end
+
+        # Verify a request
+        def verify_request(request)
+          headers = extract_headers(request)
+          body = extract_body(request)
+
+          signature_data = WebhookSignature.extract_from_headers(headers)
+
+          WebhookSignature.verify!(
+            payload: body,
+            signature: signature_data[:signature],
+            timestamp: signature_data[:timestamp],
+            secret: secret
+          )
+        end
+
+        # Parse and verify a request
+        def parse_and_verify(request)
+          verify_request(request)
+
+          body = extract_body(request)
+          JSON.parse(body, symbolize_names: true)
+        rescue JSON::ParserError => e
+          raise SignatureVerificationError, "Invalid JSON payload: #{e.message}"
+        end
+
+        private
+
+        def validate_secret!
+          raise ArgumentError, "Webhook secret is required" if secret.nil? || secret.empty?
+        end
+
+        def extract_headers(request)
+          case request
+          when Hash
+            request[:headers] || request["headers"] || {}
+          when defined?(Rack::Request) && Rack::Request
+            request.env.select { |k, _| k.start_with?("HTTP_") }.transform_keys { |k| k.sub(/^HTTP_/, "").downcase }
+          when defined?(ActionDispatch::Request) && ActionDispatch::Request
+            request.headers.to_h
+          else
+            raise ArgumentError, "Unsupported request type: #{request.class}"
+          end
+        end
+
+        def extract_body(request)
+          case request
+          when Hash
+            request[:body] || request["body"] || ""
+          when defined?(Rack::Request) && Rack::Request
+            request.body.rewind
+            request.body.read
+          when defined?(ActionDispatch::Request) && ActionDispatch::Request
+            request.raw_post
+          else
+            raise ArgumentError, "Unsupported request type: #{request.class}"
+          end
+        end
+      end
+
+      # Raised when webhook signature verification fails
+      class SignatureVerificationError < StandardError; end
+    end
+  end
+end

data/lib/attio/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Attio
+  # Current version of the Attio Ruby gem
+  VERSION = "0.1.0"
+end

data/lib/attio/webhook/event.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Attio
+  module WebhookUtils
+    # Represents a webhook event payload
+    class Event
+      attr_reader :id, :type, :occurred_at, :data, :raw_data
+
+      def initialize(payload)
+        @raw_data = payload.is_a?(String) ? JSON.parse(payload) : payload
+        @id = @raw_data["id"] || @raw_data[:id]
+        @type = @raw_data["type"] || @raw_data[:type]
+        @occurred_at = parse_timestamp(@raw_data["occurred_at"] || @raw_data[:occurred_at])
+        @data = @raw_data["data"] || @raw_data[:data] || {}
+      end
+
+      # Get the object type from the event data
+      def object_type
+        @data["object"] || @data[:object]
+      end
+
+      # Get the record from the event data
+      def record
+        @data["record"] || @data[:record]
+      end
+
+      # Get the record ID
+      def record_id
+        record_data = record
+        return nil unless record_data
+
+        record_data["id"] || record_data[:id]
+      end
+
+      # Get the record data
+      def record_data
+        record || {}
+      end
+
+      # Get changes from updated events
+      def changes
+        @data["changes"] || @data[:changes]
+      end
+
+      # Add present? method to match Rails expectations
+      def present?
+        true # Events are always present if they exist
+      end
+
+      # Check if this is a record event
+      def record_event?
+        type&.start_with?("record.")
+      end
+
+      # Check if this is a created event
+      def created_event?
+        type&.end_with?(".created")
+      end
+
+      # Check if this is an updated event
+      def updated_event?
+        type&.end_with?(".updated")
+      end
+
+      # Check if this is a deleted event
+      def deleted_event?
+        type&.end_with?(".deleted")
+      end
+
+      # Check if this is a list entry event
+      def list_entry_event?
+        type&.start_with?("list_entry.")
+      end
+
+      # Check if this is a note event
+      def note_event?
+        type&.start_with?("note.")
+      end
+
+      # Check if this is a task event
+      def task_event?
+        type&.start_with?("task.")
+      end
+
+      # Convert to hash
+      def to_h
+        {
+          id: id,
+          type: type,
+          occurred_at: occurred_at&.iso8601,
+          object_type: object_type,
+          record_id: record_id,
+          record_data: record_data,
+          changes: changes,
+          data: data
+        }.compact
+      end
+
+      # Convert event back to JSON
+      def to_json(*args)
+        @raw_data.to_json(*args)
+      end
+
+      private
+
+      def parse_timestamp(timestamp_str)
+        return nil unless timestamp_str
+        Time.parse(timestamp_str)
+      rescue ArgumentError
+        nil
+      end
+    end
+  end
+end

data/lib/attio/webhook/signature_verifier.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Attio
+  module WebhookUtils
+    # Verifies webhook signatures to ensure payloads are from Attio
+    class SignatureVerifier
+      TOLERANCE = 300 # 5 minutes in seconds
+
+      def initialize(secret)
+        @secret = secret
+      end
+
+      # Verify the webhook signature
+      # @param payload [String] The raw request body
+      # @param signature_header [String] The signature header from the request
+      # @param tolerance [Integer] Maximum age of timestamp in seconds
+      # @return [Boolean] True if signature is valid
+      def verify(payload, signature_header, tolerance: TOLERANCE)
+        timestamp, signature = parse_signature_header(signature_header)
+        return false unless timestamp && signature
+
+        # Check timestamp tolerance
+        current_time = Time.now.to_i
+        if (current_time - timestamp.to_i).abs > tolerance
+          return false
+        end
+
+        # Generate expected signature
+        signed_payload = "#{timestamp}.#{payload}"
+        expected_signature = OpenSSL::HMAC.hexdigest("SHA256", @secret, signed_payload)
+
+        # Compare signatures securely
+        secure_compare(signature, expected_signature)
+      end
+
+      private
+
+      # Parse the signature header format: "t=timestamp v1=signature"
+      def parse_signature_header(header)
+        return [nil, nil] unless header
+
+        timestamp = nil
+        signature = nil
+
+        header.split(/[,\s]+/).each do |element|
+          key, value = element.split("=", 2)
+          case key
+          when "t"
+            timestamp = value
+          when "v1"
+            signature = value
+          end
+        end
+
+        [timestamp, signature]
+      end
+
+      # Secure string comparison to prevent timing attacks
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        l = a.unpack("C*")
+        r = b.unpack("C*")
+        result = 0
+
+        l.zip(r) { |x, y| result |= x ^ y }
+        result == 0
+      end
+    end
+  end
+end