carddb 0.2.0

data/lib/carddb/configuration.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module CardDB
+  # Configuration class for CardDB client settings.
+  #
+  # @example Basic configuration
+  #   CardDB.configure do |config|
+  #     config.api_key = "carddb_xxx"
+  #   end
+  #
+  # @example With defaults and restrictions
+  #   CardDB.configure do |config|
+  #     config.api_key = "carddb_xxx"
+  #     config.default_publisher = "pokemon-company"
+  #     config.default_game = "pokemon-tcg"
+  #     config.allowed_publishers = ["pokemon-company"]
+  #     config.allowed_games = { "pokemon-company" => ["pokemon-tcg"] }
+  #   end
+  #
+  # @example With logging
+  #   CardDB.configure do |config|
+  #     config.api_key = "carddb_xxx"
+  #     config.logger = Logger.new(STDOUT)
+  #     config.log_level = :debug
+  #   end
+  #
+  # @example With auto-retry on rate limit
+  #   CardDB.configure do |config|
+  #     config.api_key = "carddb_xxx"
+  #     config.retry_on_rate_limit = true
+  #     config.max_retries = 3
+  #   end
+  class Configuration
+    # Default API endpoint
+    DEFAULT_ENDPOINT = 'https://carddb.xtda.org/query'
+
+    # Default timeouts in seconds
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+
+    # Default retry settings
+    DEFAULT_MAX_RETRIES = 3
+
+    # @return [String, nil] API key for authentication
+    attr_accessor :api_key
+
+    # @return [String] GraphQL endpoint URL
+    attr_accessor :endpoint
+
+    # @return [Integer] Request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] Connection open timeout in seconds
+    attr_accessor :open_timeout
+
+    # @return [String, nil] Default publisher slug for queries
+    attr_accessor :default_publisher
+
+    # @return [String, nil] Default game key for queries
+    attr_accessor :default_game
+
+    # @return [Array<String>, nil] List of allowed publisher slugs (nil = all allowed)
+    attr_accessor :allowed_publishers
+
+    # @return [Hash<String, Array<String>>, nil] Map of publisher slug to allowed game keys
+    attr_accessor :allowed_games
+
+    # @return [Logger, nil] Logger instance for debug output
+    attr_accessor :logger
+
+    # @return [Symbol] Log level (:debug, :info, :warn, :error)
+    attr_accessor :log_level
+
+    # @return [Boolean] Whether to automatically retry on rate limit errors
+    attr_accessor :retry_on_rate_limit
+
+    # @return [Integer] Maximum number of retries on rate limit
+    attr_accessor :max_retries
+
+    # @return [Object, nil] Cache instance (must respond to read/write, e.g., Rails.cache or MemoryCache)
+    attr_accessor :cache
+
+    # @return [Integer] Default cache TTL in seconds (default: 300 = 5 minutes)
+    attr_accessor :cache_ttl
+
+    # @return [Hash<Symbol, Integer>] Per-resource cache TTLs in seconds
+    #   Keys are resource names (:publishers, :games, :datasets, :records)
+    #   Values override the default cache_ttl for that resource
+    attr_accessor :cache_ttls
+
+    def initialize
+      @endpoint = DEFAULT_ENDPOINT
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @api_key = nil
+      @default_publisher = nil
+      @default_game = nil
+      @allowed_publishers = nil
+      @allowed_games = nil
+      @logger = nil
+      @log_level = :info
+      @retry_on_rate_limit = false
+      @max_retries = DEFAULT_MAX_RETRIES
+      @cache = nil
+      @cache_ttl = 300
+      @cache_ttls = {}
+    end
+
+    # Get the cache TTL for a specific resource.
+    # Falls back to the default cache_ttl if no resource-specific TTL is configured.
+    #
+    # @param resource [Symbol, String] The resource name (:publishers, :games, :datasets, :records)
+    # @return [Integer] The TTL in seconds
+    def cache_ttl_for(resource)
+      cache_ttls[resource.to_sym] || cache_ttl
+    end
+
+    # Validates that a publisher is allowed by the configuration.
+    #
+    # @param publisher_slug [String] The publisher slug to validate
+    # @raise [CardDB::RestrictedError] if the publisher is not in the allowed list
+    # @return [void]
+    def validate_publisher!(publisher_slug)
+      return if allowed_publishers.nil?
+      return if allowed_publishers.include?(publisher_slug)
+
+      raise RestrictedError, "Publisher '#{publisher_slug}' is not in the allowed publishers list"
+    end
+
+    # Validates that a game is allowed by the configuration.
+    #
+    # @param publisher_slug [String] The publisher slug
+    # @param game_key [String] The game key to validate
+    # @raise [CardDB::RestrictedError] if the game is not in the allowed list
+    # @return [void]
+    def validate_game!(publisher_slug, game_key)
+      return if allowed_games.nil?
+      return unless allowed_games.key?(publisher_slug)
+
+      allowed = allowed_games[publisher_slug]
+      return if allowed.include?(game_key)
+
+      raise RestrictedError, "Game '#{game_key}' is not allowed for publisher '#{publisher_slug}'"
+    end
+
+    # Validates both publisher and game if provided.
+    #
+    # @param publisher_slug [String, nil] The publisher slug
+    # @param game_key [String, nil] The game key
+    # @raise [CardDB::RestrictedError] if validation fails
+    # @return [void]
+    def validate_access!(publisher_slug, game_key = nil)
+      validate_publisher!(publisher_slug) if publisher_slug
+      validate_game!(publisher_slug, game_key) if publisher_slug && game_key
+    end
+
+    # Resolves the publisher slug, using the default if not provided.
+    #
+    # @param publisher_slug [String, nil] The provided publisher slug
+    # @return [String, nil] The resolved publisher slug
+    def resolve_publisher(publisher_slug)
+      publisher_slug || default_publisher
+    end
+
+    # Resolves the game key, using the default if not provided.
+    #
+    # @param game_key [String, nil] The provided game key
+    # @return [String, nil] The resolved game key
+    def resolve_game(game_key)
+      game_key || default_game
+    end
+
+    # Creates a copy of this configuration with optional overrides.
+    #
+    # @param overrides [Hash] Configuration options to override
+    # @return [Configuration] A new configuration instance
+    def merge(overrides = {})
+      dup.tap do |config|
+        overrides.each do |key, value|
+          config.public_send(:"#{key}=", value) if config.respond_to?(:"#{key}=")
+        end
+      end
+    end
+  end
+end

data/lib/carddb/connection.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'json'
+
+module CardDB
+  # HTTP connection wrapper using Faraday.
+  # Handles authentication, request/response formatting, and error handling.
+  class Connection
+    # @return [Configuration] The configuration for this connection
+    attr_reader :config
+
+    # @param config [Configuration] The configuration to use
+    def initialize(config)
+      @config = config
+    end
+
+    # Executes a GraphQL query.
+    #
+    # @param query [String] The GraphQL query string
+    # @param variables [Hash] Query variables
+    # @return [Hash] The response data
+    # @raise [CardDB::Error] Various errors based on response
+    def execute(query, variables = {})
+      operation_name = extract_operation_name(query)
+      retries = 0
+
+      begin
+        start_time = Time.now
+        log_request(operation_name, variables)
+
+        response = connection.post do |req|
+          req.body = JSON.generate({ query: query, variables: variables })
+        end
+
+        duration_ms = ((Time.now - start_time) * 1000).round
+        result = handle_response(response)
+
+        log_response(operation_name, duration_ms)
+        result
+      rescue RateLimitError => e
+        if config.retry_on_rate_limit && retries < config.max_retries
+          retries += 1
+          sleep_time = e.retry_after || 60
+          log_rate_limit_retry(operation_name, retries, sleep_time)
+          sleep(sleep_time)
+          retry
+        end
+        raise
+      rescue Faraday::TimeoutError => e
+        log_error("Request timed out: #{e.message}")
+        raise TimeoutError, "Request timed out: #{e.message}"
+      rescue Faraday::ConnectionFailed => e
+        log_error("Connection failed: #{e.message}")
+        raise ConnectionError, "Connection failed: #{e.message}"
+      rescue Faraday::Error => e
+        log_error("HTTP error: #{e.message}")
+        raise ConnectionError, "HTTP error: #{e.message}"
+      end
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: config.endpoint) do |f|
+        f.request :retry, max: 2, interval: 0.5, backoff_factor: 2,
+                          exceptions: [Faraday::TimeoutError, Faraday::ConnectionFailed]
+
+        f.headers['Content-Type'] = 'application/json'
+        f.headers['Accept'] = 'application/json'
+        f.headers['User-Agent'] = "CardDB-SDK/ruby/#{CardDB::VERSION} (ruby/#{RUBY_VERSION})"
+
+        # Set API key header if configured
+        f.headers['X-API-Key'] = config.api_key if config.api_key
+
+        f.options.timeout = config.timeout
+        f.options.open_timeout = config.open_timeout
+
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200
+        handle_success_response(response)
+      when 401
+        raise AuthenticationError, 'Invalid or missing API key'
+      when 429
+        handle_rate_limit_response(response)
+      when 400..499
+        handle_client_error(response)
+      when 500..599
+        raise ServerError.new("Server error (#{response.status})", status: response.status,
+                                                                   response: parse_body(response))
+      else
+        raise Error, "Unexpected response status: #{response.status}"
+      end
+    end
+
+    def handle_success_response(response)
+      body = parse_body(response)
+
+      # Check for GraphQL errors
+      handle_graphql_errors(body['errors'], body) if body['errors']&.any?
+
+      # Extract rate limit headers for informational purposes
+      extract_rate_limit_info(response)
+
+      body['data']
+    end
+
+    def handle_graphql_errors(errors, body)
+      # Check for specific error types
+      first_error = errors.first
+      message = first_error&.dig('message') || 'GraphQL error'
+      extensions = first_error&.dig('extensions') || {}
+
+      case extensions['code']
+      when 'UNAUTHENTICATED'
+        raise AuthenticationError, message
+      when 'RATE_LIMITED'
+        raise RateLimitError.new(message, response: body)
+      when 'NOT_FOUND'
+        raise NotFoundError, message
+      when 'VALIDATION_ERROR', 'BAD_USER_INPUT'
+        raise ValidationError.new(message, errors: errors, response: body)
+      else
+        raise GraphQLError.new(message, errors: errors, response: body)
+      end
+    end
+
+    def handle_rate_limit_response(response)
+      retry_after = response.headers['Retry-After']&.to_i
+      limit = response.headers['X-RateLimit-Limit']&.to_i
+      remaining = response.headers['X-RateLimit-Remaining']&.to_i
+      reset = response.headers['X-RateLimit-Reset']&.to_i
+      reset_at = reset ? Time.at(reset) : nil
+
+      raise RateLimitError.new(
+        'Rate limit exceeded',
+        retry_after: retry_after || 60,
+        limit: limit,
+        remaining: remaining,
+        reset_at: reset_at,
+        response: parse_body(response)
+      )
+    end
+
+    def handle_client_error(response)
+      body = parse_body(response)
+      message = body.dig('errors', 0, 'message') || "Client error (#{response.status})"
+      raise ValidationError.new(message, response: body)
+    end
+
+    def parse_body(response)
+      JSON.parse(response.body)
+    rescue JSON::ParserError
+      { 'raw' => response.body }
+    end
+
+    def extract_rate_limit_info(response)
+      # Store rate limit info in thread-local for potential access
+      Thread.current[:carddb_rate_limit] = {
+        limit: response.headers['X-RateLimit-Limit']&.to_i,
+        remaining: response.headers['X-RateLimit-Remaining']&.to_i,
+        reset: response.headers['X-RateLimit-Reset']&.to_i
+      }.compact
+    end
+
+    # Logging helpers
+
+    def extract_operation_name(query)
+      # Extract operation name from query like "query SearchGames(...)"
+      match = query.match(/(?:query|mutation)\s+(\w+)/)
+      match ? match[1] : 'Unknown'
+    end
+
+    def log_request(operation_name, variables)
+      return unless logger
+
+      return unless log_level?(:debug)
+
+      sanitized_vars = variables.transform_keys(&:to_s)
+      logger.debug("[CardDB] Executing #{operation_name} with variables: #{sanitized_vars.inspect}")
+    end
+
+    def log_response(operation_name, duration_ms)
+      return unless logger
+
+      return unless log_level?(:info)
+
+      logger.info("[CardDB] #{operation_name} completed in #{duration_ms}ms")
+    end
+
+    def log_rate_limit_retry(operation_name, retry_count, sleep_time)
+      return unless logger
+
+      return unless log_level?(:warn)
+
+      logger.warn("[CardDB] Rate limited on #{operation_name}, retry #{retry_count}/#{config.max_retries} after #{sleep_time}s")
+    end
+
+    def log_error(message)
+      return unless logger
+
+      return unless log_level?(:error)
+
+      logger.error("[CardDB] #{message}")
+    end
+
+    def logger
+      config.logger
+    end
+
+    def log_level?(level)
+      levels = { debug: 0, info: 1, warn: 2, error: 3 }
+      configured_level = levels[config.log_level] || 1
+      requested_level = levels[level] || 1
+      requested_level >= configured_level
+    end
+  end
+end

data/lib/carddb/errors.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module CardDB
+  # Base error class for all CardDB errors
+  class Error < StandardError
+    # @return [Hash, nil] The full response body if available
+    attr_reader :response
+
+    def initialize(message = nil, response: nil)
+      @response = response
+      super(message)
+    end
+  end
+
+  # Raised when authentication fails (invalid API key or token)
+  class AuthenticationError < Error; end
+
+  # Raised when rate limits are exceeded
+  class RateLimitError < Error
+    # @return [Integer, nil] Seconds until rate limit resets
+    attr_reader :retry_after
+
+    # @return [Integer, nil] Maximum requests allowed
+    attr_reader :limit
+
+    # @return [Integer, nil] Remaining requests in window
+    attr_reader :remaining
+
+    # @return [Time, nil] Time when the rate limit resets
+    attr_reader :reset_at
+
+    def initialize(message = nil, retry_after: nil, limit: nil, remaining: nil, reset_at: nil, response: nil)
+      @retry_after = retry_after
+      @limit = limit
+      @remaining = remaining
+      @reset_at = reset_at
+      super(message, response: response)
+    end
+  end
+
+  # Raised when a requested resource is not found
+  class NotFoundError < Error; end
+
+  # Raised when request validation fails
+  class ValidationError < Error
+    # @return [Array<Hash>] List of validation errors
+    attr_reader :errors
+
+    def initialize(message = nil, errors: [], response: nil)
+      @errors = errors
+      super(message, response: response)
+    end
+  end
+
+  # Raised when accessing a restricted publisher or game
+  class RestrictedError < Error; end
+
+  # Raised for GraphQL-level errors
+  class GraphQLError < Error
+    # @return [Array<Hash>] List of GraphQL errors
+    attr_reader :errors
+
+    def initialize(message = nil, errors: [], response: nil)
+      @errors = errors
+      super(message, response: response)
+    end
+  end
+
+  # Raised for network/connection issues
+  class ConnectionError < Error; end
+
+  # Raised when the server returns an unexpected response
+  class ServerError < Error
+    # @return [Integer, nil] HTTP status code
+    attr_reader :status
+
+    def initialize(message = nil, status: nil, response: nil)
+      @status = status
+      super(message, response: response)
+    end
+  end
+
+  # Raised when request times out
+  class TimeoutError < ConnectionError; end
+end

data/lib/carddb/filter_builder.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module CardDB
+  # DSL for building filter queries in a Ruby-friendly way.
+  #
+  # @example Basic usage
+  #   filter = CardDB::FilterBuilder.build do
+  #     where(name: "Pikachu")
+  #     where(hp: gte(100))
+  #   end
+  #
+  # @example Complex filters with OR
+  #   filter = CardDB::FilterBuilder.build do
+  #     where(type: "creature")
+  #     any do
+  #       where(color: "red")
+  #       where(color: "blue")
+  #     end
+  #   end
+  class FilterBuilder
+    # Operator wrapper classes for DSL
+    class Operator
+      attr_reader :op, :value
+
+      def initialize(op, value)
+        @op = op
+        @value = value
+      end
+
+      def to_filter
+        { op => value }
+      end
+    end
+
+    # Build a filter using the DSL
+    #
+    # @yield Block to define filters
+    # @return [Hash] The filter hash
+    def self.build(&block)
+      builder = new
+      builder.instance_eval(&block)
+      builder.to_filter
+    end
+
+    def initialize
+      @conditions = []
+      @or_groups = []
+    end
+
+    # Add a condition to the filter
+    #
+    # @param conditions [Hash] Field conditions
+    # @return [self]
+    def where(conditions)
+      conditions.each do |field, value|
+        @conditions << build_condition(field, value)
+      end
+      self
+    end
+
+    # Add an OR group
+    #
+    # @yield Block to define OR conditions
+    # @return [self]
+    def any(&block)
+      or_builder = FilterBuilder.new
+      or_builder.instance_eval(&block)
+      or_conditions = or_builder.conditions_array
+      @or_groups << { '$or' => or_conditions } if or_conditions.any?
+      self
+    end
+
+    # Add a link filter condition
+    #
+    # @param field [Symbol, String] The link field name
+    # @param conditions [Hash] Conditions on the linked record
+    # @return [self]
+    def where_link(field, conditions)
+      link_filter = {}
+      conditions.each do |key, value|
+        link_filter[key.to_s] = value.is_a?(Operator) ? value.to_filter : value
+      end
+      @conditions << { "#{field}._link" => link_filter }
+      self
+    end
+
+    # Add an array element filter (for ARRAY of HASH fields)
+    #
+    # @param field [Symbol, String] The array field name
+    # @param conditions [Hash] Conditions that any element must match
+    # @return [self]
+    def where_any(field, conditions)
+      any_filter = {}
+      conditions.each do |key, value|
+        any_filter[key.to_s] = value.is_a?(Operator) ? value.to_filter : value
+      end
+      @conditions << { "#{field}._any" => any_filter }
+      self
+    end
+
+    # Convert to filter hash
+    #
+    # @return [Hash]
+    def to_filter
+      all_conditions = @conditions + @or_groups
+      return {} if all_conditions.empty?
+      return all_conditions.first if all_conditions.size == 1
+
+      { '$and' => all_conditions }
+    end
+
+    # Get conditions as array (for OR groups)
+    #
+    # @return [Array<Hash>]
+    def conditions_array
+      @conditions
+    end
+
+    private
+
+    def build_condition(field, value)
+      field_str = field.to_s
+
+      case value
+      when Operator
+        { field_str => value.to_filter }
+      when Hash
+        # Nested conditions (e.g., stats: { power: gte(3) })
+        nested = {}
+        value.each do |k, v|
+          nested[k.to_s] = v.is_a?(Operator) ? v.to_filter : v
+        end
+        { field_str => nested }
+      else
+        # Simple equality
+        { field_str => value }
+      end
+    end
+  end
+
+  # Module with operator helper methods
+  # Include this to use operators in filter blocks
+  module FilterOperators
+    # Equality operator
+    def eq(value)
+      FilterBuilder::Operator.new('eq', value)
+    end
+
+    # Not equal operator
+    def neq(value)
+      FilterBuilder::Operator.new('neq', value)
+    end
+
+    # Greater than operator
+    def gt(value)
+      FilterBuilder::Operator.new('gt', value)
+    end
+
+    # Greater than or equal operator
+    def gte(value)
+      FilterBuilder::Operator.new('gte', value)
+    end
+
+    # Less than operator
+    def lt(value)
+      FilterBuilder::Operator.new('lt', value)
+    end
+
+    # Less than or equal operator
+    def lte(value)
+      FilterBuilder::Operator.new('lte', value)
+    end
+
+    # In array operator
+    def within(values)
+      FilterBuilder::Operator.new('in', values)
+    end
+
+    # Not in array operator
+    def not_within(values)
+      FilterBuilder::Operator.new('nin', values)
+    end
+
+    # Array contains operator
+    def contains(value)
+      FilterBuilder::Operator.new('contains', value)
+    end
+
+    # Like pattern operator (case-sensitive)
+    def like(pattern)
+      FilterBuilder::Operator.new('like', pattern)
+    end
+
+    # Like pattern operator (case-insensitive)
+    def ilike(pattern)
+      FilterBuilder::Operator.new('ilike', pattern)
+    end
+
+    # Is null operator
+    def is_null
+      FilterBuilder::Operator.new('is_null', true)
+    end
+
+    # Is not null operator
+    def is_not_null
+      FilterBuilder::Operator.new('is_null', false)
+    end
+  end
+
+  # Make operators available in FilterBuilder instances
+  class FilterBuilder
+    include FilterOperators
+  end
+end