exaonruby 1.0.0

data/lib/exa/resources/webset_item.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Resources
+    class WebsetItem < Base
+      # @return [String] Unique identifier
+      def id
+        get(:id)
+      end
+
+      # @return [String] Object type (always "webset_item")
+      def object
+        get(:object)
+      end
+
+      # @return [String] Source type: search, import
+      def source
+        get(:source)
+      end
+
+      # @return [String, nil] Source identifier
+      def source_id
+        get(:source_id)
+      end
+
+      # @return [String] Parent webset ID
+      def webset_id
+        get(:webset_id)
+      end
+
+      # @return [WebsetItemProperties, nil] Item properties
+      def properties
+        props = get(:properties)
+        return nil unless props
+
+        WebsetItemProperties.new(props)
+      end
+
+      # @return [Array<WebsetItemEvaluation>] Evaluation results
+      def evaluations
+        @evaluations ||= (get(:evaluations, []) || []).map { |data| WebsetItemEvaluation.new(data) }
+      end
+
+      # @return [Array<WebsetItemEnrichmentResult>] Enrichment results
+      def enrichments
+        @enrichments ||= (get(:enrichments, []) || []).map { |data| WebsetItemEnrichmentResult.new(data) }
+      end
+
+      # @return [Time, nil] Creation timestamp
+      def created_at
+        parse_time(get(:created_at))
+      end
+
+      # @return [Time, nil] Last update timestamp
+      def updated_at
+        parse_time(get(:updated_at))
+      end
+
+      # @return [String, nil] Item type from properties
+      def type
+        dig(:properties, :type)
+      end
+
+      # @return [String, nil] URL from properties
+      def url
+        dig(:properties, :url)
+      end
+
+      # @return [String, nil] Description from properties
+      def description
+        dig(:properties, :description)
+      end
+
+      # @return [Boolean] Whether all evaluations passed
+      def all_criteria_satisfied?
+        evaluations.all?(&:satisfied?)
+      end
+
+      # @return [Array<WebsetItemEvaluation>] Failed evaluations
+      def failed_evaluations
+        evaluations.reject(&:satisfied?)
+      end
+
+      private
+
+      def parse_time(value)
+        return nil unless value
+
+        Time.parse(value)
+      rescue ArgumentError
+        nil
+      end
+
+      def inspectable_attributes
+        { id: id, type: type, url: url }
+      end
+    end
+
+    class WebsetItemProperties < Base
+      # @return [String, nil] Entity type: person, company, research_paper
+      def type
+        get(:type)
+      end
+
+      # @return [String, nil] URL
+      def url
+        get(:url)
+      end
+
+      # @return [String, nil] Description
+      def description
+        get(:description)
+      end
+
+      # @return [Hash, nil] Person information if type is person
+      def person
+        get(:person)
+      end
+
+      # @return [Hash, nil] Company information if type is company
+      def company
+        get(:company)
+      end
+
+      # @return [Hash, nil] Research paper information if type is research_paper
+      def research_paper
+        get(:research_paper)
+      end
+
+      # Person attributes (when type is person)
+
+      # @return [String, nil] Person's name
+      def person_name
+        dig(:person, :name)
+      end
+
+      # @return [String, nil] Person's location
+      def person_location
+        dig(:person, :location)
+      end
+
+      # @return [String, nil] Person's position/title
+      def person_position
+        dig(:person, :position)
+      end
+
+      # @return [String, nil] Person's company name
+      def person_company_name
+        dig(:person, :company, :name)
+      end
+
+      # @return [String, nil] Person's picture URL
+      def person_picture_url
+        dig(:person, :picture_url)
+      end
+
+      # Company attributes (when type is company)
+
+      # @return [String, nil] Company name
+      def company_name
+        dig(:company, :name)
+      end
+
+      # @return [String, nil] Company location
+      def company_location
+        dig(:company, :location)
+      end
+    end
+
+    class WebsetItemEvaluation < Base
+      # @return [String, nil] Criterion description
+      def criterion
+        get(:criterion)
+      end
+
+      # @return [String, nil] Reasoning for the evaluation
+      def reasoning
+        get(:reasoning)
+      end
+
+      # @return [String, nil] Satisfaction status: yes, no, unknown
+      def satisfied_status
+        get(:satisfied)
+      end
+
+      # @return [Boolean] Whether the criterion was satisfied
+      def satisfied?
+        satisfied_status == "yes"
+      end
+
+      # @return [Boolean] Whether satisfaction is unknown
+      def unknown?
+        satisfied_status == "unknown"
+      end
+
+      # @return [Array<Hash>] References supporting the evaluation
+      def references
+        get(:references, [])
+      end
+    end
+
+    class WebsetItemEnrichmentResult < Base
+      # @return [String] Object type
+      def object
+        get(:object)
+      end
+
+      # @return [String] Status: pending, completed, failed
+      def status
+        get(:status)
+      end
+
+      # @return [String, nil] Format: text, enum, number, boolean, date
+      def format
+        get(:format)
+      end
+
+      # @return [Array, String, Integer, Boolean, nil] Result value(s)
+      def result
+        get(:result)
+      end
+
+      # @return [String, nil] Reasoning for the result
+      def reasoning
+        get(:reasoning)
+      end
+
+      # @return [Array<Hash>] References used
+      def references
+        get(:references, [])
+      end
+
+      # @return [String, nil] Parent enrichment ID
+      def enrichment_id
+        get(:enrichment_id)
+      end
+
+      # @return [Boolean] Whether completed successfully
+      def completed?
+        status == "completed"
+      end
+
+      # @return [Boolean] Whether still pending
+      def pending?
+        status == "pending"
+      end
+
+      # @return [Boolean] Whether failed
+      def failed?
+        status == "failed"
+      end
+    end
+  end
+end

data/lib/exa/utils/parameter_converter.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  module Utils
+    class ParameterConverter
+      SNAKE_TO_CAMEL_MAP = {
+        api_key: :apiKey,
+        num_results: :numResults,
+        include_domains: :includeDomains,
+        exclude_domains: :excludeDomains,
+        start_crawl_date: :startCrawlDate,
+        end_crawl_date: :endCrawlDate,
+        start_published_date: :startPublishedDate,
+        end_published_date: :endPublishedDate,
+        include_text: :includeText,
+        exclude_text: :excludeText,
+        additional_queries: :additionalQueries,
+        user_location: :userLocation,
+        livecrawl_timeout: :livecrawlTimeout,
+        subpage_target: :subpageTarget,
+        highlight_query: :highlightQuery,
+        num_sentences: :numSentences,
+        max_characters: :maxCharacters,
+        external_id: :externalId,
+        source_id: :sourceId,
+        webset_id: :websetId,
+        search_id: :searchId,
+        enrichment_id: :enrichmentId,
+        item_id: :itemId,
+        success_rate: :successRate,
+        time_left: :timeLeft,
+        next_cursor: :nextCursor,
+        has_more: :hasMore,
+        created_at: :createdAt,
+        updated_at: :updatedAt,
+        canceled_at: :canceledAt,
+        canceled_reason: :canceledReason,
+        failed_at: :failedAt,
+        failed_reason: :failedReason,
+        failed_message: :failedMessage,
+        last_run: :lastRun,
+        next_run_at: :nextRunAt,
+        picture_url: :pictureUrl,
+        cost_dollars: :costDollars,
+        request_id: :requestId,
+        resolved_search_type: :resolvedSearchType,
+        search_type: :searchType,
+        published_date: :publishedDate,
+        highlight_scores: :highlightScores
+      }.freeze
+
+      CAMEL_TO_SNAKE_MAP = SNAKE_TO_CAMEL_MAP.invert.freeze
+
+      class << self
+        # Converts Ruby-style snake_case keys to API-style camelCase
+        # @param hash [Hash] Hash with snake_case keys
+        # @return [Hash] Hash with camelCase keys
+        def to_api_params(hash)
+          return hash unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) do |(key, value), result|
+            api_key = convert_key_to_camel(key)
+            result[api_key] = convert_value_to_api(value)
+          end
+        end
+
+        # Converts API-style camelCase keys to Ruby-style snake_case
+        # @param hash [Hash] Hash with camelCase keys
+        # @return [Hash] Hash with snake_case keys
+        def from_api_response(hash)
+          return hash unless hash.is_a?(Hash)
+
+          hash.each_with_object({}) do |(key, value), result|
+            ruby_key = convert_key_to_snake(key)
+            result[ruby_key] = convert_value_from_api(value)
+          end
+        end
+
+        # Formats a Time or Date object to ISO 8601 string
+        # @param value [Time, Date, String, nil] Value to format
+        # @return [String, nil] ISO 8601 formatted string
+        def format_date(value)
+          case value
+          when Time
+            value.utc.iso8601(3)
+          when Date
+            value.to_time.utc.iso8601(3)
+          when String
+            value
+          end
+        end
+
+        # Parses an ISO 8601 string to Time object
+        # @param value [String, nil] ISO 8601 string
+        # @return [Time, nil] Parsed Time object
+        def parse_date(value)
+          return nil unless value.is_a?(String)
+
+          Time.parse(value)
+        rescue ArgumentError
+          nil
+        end
+
+        private
+
+        # @param key [Symbol, String] Key to convert
+        # @return [String] camelCase key
+        def convert_key_to_camel(key)
+          sym_key = key.to_sym
+          return SNAKE_TO_CAMEL_MAP[sym_key].to_s if SNAKE_TO_CAMEL_MAP.key?(sym_key)
+
+          key.to_s.gsub(/_([a-z])/) { ::Regexp.last_match(1).upcase }
+        end
+
+        # @param key [Symbol, String] Key to convert
+        # @return [Symbol] snake_case key
+        def convert_key_to_snake(key)
+          str_key = key.to_s
+          sym_key = key.to_sym
+          return CAMEL_TO_SNAKE_MAP[sym_key] if CAMEL_TO_SNAKE_MAP.key?(sym_key)
+
+          str_key.gsub(/([A-Z])/) { "_#{::Regexp.last_match(1).downcase}" }.to_sym
+        end
+
+        # @param value [Object] Value to convert for API
+        # @return [Object] Converted value
+        def convert_value_to_api(value)
+          case value
+          when Hash
+            to_api_params(value)
+          when Array
+            value.map { |v| convert_value_to_api(v) }
+          when Time, Date
+            format_date(value)
+          when Symbol
+            value.to_s.gsub("_", " ")
+          else
+            value
+          end
+        end
+
+        # @param value [Object] Value from API response
+        # @return [Object] Converted value
+        def convert_value_from_api(value)
+          case value
+          when Hash
+            from_api_response(value)
+          when Array
+            value.map { |v| convert_value_from_api(v) }
+          else
+            value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/exa/utils/webhook_handler.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+require "openssl"
+require "json"
+
+module Exa
+  module Utils
+    # Webhook signature verification and payload handling for n8n, Zapier, and direct integrations
+    #
+    # This module provides utilities for verifying Exa webhook signatures and
+    # parsing webhook payloads. It can be used with any webhook receiver including
+    # Rails, Sinatra, n8n, Zapier, or custom Ruby applications.
+    #
+    # @example Verify a webhook in Rails
+    #   class WebhooksController < ApplicationController
+    #     skip_before_action :verify_authenticity_token
+    #
+    #     def exa
+    #       raw_body = request.raw_post
+    #       signature = request.headers["X-Exa-Signature"]
+    #       timestamp = request.headers["X-Exa-Timestamp"]
+    #
+    #       if Exa::Utils::WebhookHandler.verify_signature(raw_body, signature, secret: ENV["EXA_WEBHOOK_SECRET"])
+    #         event = Exa::Utils::WebhookHandler.parse_event(raw_body)
+    #         process_event(event)
+    #         head :ok
+    #       else
+    #         head :unauthorized
+    #       end
+    #     end
+    #   end
+    #
+    # @example Verify in Sinatra
+    #   post "/webhooks/exa" do
+    #     raw_body = request.body.read
+    #     signature = request.env["HTTP_X_EXA_SIGNATURE"]
+    #
+    #     if Exa::Utils::WebhookHandler.verify_signature(raw_body, signature, secret: ENV["EXA_WEBHOOK_SECRET"])
+    #       event = Exa::Utils::WebhookHandler.parse_event(raw_body)
+    #       # Process event
+    #       status 200
+    #     else
+    #       status 401
+    #     end
+    #   end
+    class WebhookHandler
+      # Default tolerance for timestamp validation (5 minutes)
+      DEFAULT_TOLERANCE = 300
+
+      # Signature header name
+      SIGNATURE_HEADER = "X-Exa-Signature"
+
+      # Timestamp header name
+      TIMESTAMP_HEADER = "X-Exa-Timestamp"
+
+      class << self
+        # Verifies the webhook signature using HMAC-SHA256
+        #
+        # @param payload [String] Raw request body
+        # @param signature [String] Signature from X-Exa-Signature header
+        # @param secret [String] Webhook secret from webhook creation
+        # @param timestamp [String, nil] Optional timestamp from X-Exa-Timestamp header
+        # @param tolerance [Integer] Maximum age of webhook in seconds (default: 300)
+        #
+        # @return [Boolean] true if signature is valid
+        #
+        # @example Basic verification
+        #   WebhookHandler.verify_signature(payload, signature, secret: "whsec_...")
+        #
+        # @example With timestamp validation
+        #   WebhookHandler.verify_signature(
+        #     payload,
+        #     signature,
+        #     secret: "whsec_...",
+        #     timestamp: request.headers["X-Exa-Timestamp"],
+        #     tolerance: 300
+        #   )
+        def verify_signature(payload, signature, secret:, timestamp: nil, tolerance: DEFAULT_TOLERANCE)
+          return false if payload.nil? || payload.empty?
+          return false if signature.nil? || signature.empty?
+          return false if secret.nil? || secret.empty?
+
+          # Validate timestamp if provided
+          if timestamp
+            return false unless valid_timestamp?(timestamp, tolerance)
+          end
+
+          # Calculate expected signature
+          expected = compute_signature(payload, secret, timestamp)
+
+          # Use secure comparison to prevent timing attacks
+          secure_compare(expected, signature)
+        end
+
+        # Computes HMAC-SHA256 signature for a payload
+        #
+        # @param payload [String] Raw request body
+        # @param secret [String] Webhook secret
+        # @param timestamp [String, nil] Optional timestamp to include
+        #
+        # @return [String] Hex-encoded signature
+        def compute_signature(payload, secret, timestamp = nil)
+          # If timestamp provided, prepend it to payload (common pattern)
+          signed_payload = timestamp ? "#{timestamp}.#{payload}" : payload
+
+          OpenSSL::HMAC.hexdigest(
+            OpenSSL::Digest.new("sha256"),
+            secret,
+            signed_payload
+          )
+        end
+
+        # Parses a webhook payload into an Event resource
+        #
+        # @param payload [String] Raw JSON request body
+        # @return [Exa::Resources::Event] Parsed event
+        #
+        # @raise [Exa::InvalidRequestError] if payload is invalid JSON
+        def parse_event(payload)
+          data = JSON.parse(payload)
+          data_symbolized = symbolize_keys(data)
+
+          Resources::Event.new(
+            ParameterConverter.from_api_response(data_symbolized)
+          )
+        rescue JSON::ParserError => e
+          raise InvalidRequestError, "Invalid webhook payload: #{e.message}"
+        end
+
+        # Parses headers from different framework formats
+        #
+        # @param headers [Hash] Request headers
+        # @return [Hash] Normalized headers with signature and timestamp
+        #
+        # @example Rails headers
+        #   WebhookHandler.extract_headers(request.headers)
+        #   # => { signature: "abc123", timestamp: "1703001234" }
+        #
+        # @example Rack headers
+        #   WebhookHandler.extract_headers(env)
+        #   # => { signature: "abc123", timestamp: "1703001234" }
+        def extract_headers(headers)
+          signature = headers["X-Exa-Signature"] ||
+                      headers["HTTP_X_EXA_SIGNATURE"] ||
+                      headers["x-exa-signature"] ||
+                      headers[:x_exa_signature]
+
+          timestamp = headers["X-Exa-Timestamp"] ||
+                      headers["HTTP_X_EXA_TIMESTAMP"] ||
+                      headers["x-exa-timestamp"] ||
+                      headers[:x_exa_timestamp]
+
+          { signature: signature, timestamp: timestamp }
+        end
+
+        # Convenience method to verify and parse in one call
+        #
+        # @param payload [String] Raw request body
+        # @param headers [Hash] Request headers
+        # @param secret [String] Webhook secret
+        # @param tolerance [Integer] Maximum age of webhook in seconds
+        #
+        # @return [Exa::Resources::Event] Parsed event if verification succeeds
+        #
+        # @raise [Exa::AuthenticationError] if signature verification fails
+        # @raise [Exa::InvalidRequestError] if payload is invalid
+        def construct_event(payload, headers, secret:, tolerance: DEFAULT_TOLERANCE)
+          extracted = extract_headers(headers)
+
+          unless verify_signature(
+            payload,
+            extracted[:signature],
+            secret: secret,
+            timestamp: extracted[:timestamp],
+            tolerance: tolerance
+          )
+            raise AuthenticationError, "Webhook signature verification failed"
+          end
+
+          parse_event(payload)
+        end
+
+        private
+
+        # Validates that timestamp is within tolerance
+        #
+        # @param timestamp [String] Unix timestamp string
+        # @param tolerance [Integer] Maximum age in seconds
+        # @return [Boolean] true if timestamp is valid
+        def valid_timestamp?(timestamp, tolerance)
+          ts = Integer(timestamp)
+          age = Time.now.to_i - ts
+          age.abs <= tolerance
+        rescue ArgumentError, TypeError
+          false
+        end
+
+        # Secure string comparison to prevent timing attacks
+        #
+        # @param a [String] First string
+        # @param b [String] Second string
+        # @return [Boolean] true if strings are equal
+        def secure_compare(a, b)
+          return false if a.nil? || b.nil?
+          return false unless a.bytesize == b.bytesize
+
+          # Use OpenSSL's secure comparison if available (Ruby 2.5+)
+          if defined?(OpenSSL.secure_compare)
+            OpenSSL.secure_compare(a, b)
+          else
+            # Fallback for older Ruby
+            result = 0
+            a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
+            result.zero?
+          end
+        end
+
+        # Recursively symbolizes hash keys
+        #
+        # @param obj [Object] Object to process
+        # @return [Object] Object with symbolized keys
+        def symbolize_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) do |(key, value), result|
+              result[key.to_sym] = symbolize_keys(value)
+            end
+          when Array
+            obj.map { |item| symbolize_keys(item) }
+          else
+            obj
+          end
+        end
+      end
+    end
+  end
+end

data/lib/exa/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# typed: strict
+
+module Exa
+  VERSION = "1.0.0"
+end