carddb 0.2.0

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/examples/basic_usage.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'carddb'
+
+# Configure the client
+CardDB.configure do |config|
+  # Optional: Set API key for higher rate limits
+  config.api_key = ENV.fetch('CARDDB_API_KEY', nil)
+
+  # Set defaults for convenience
+  config.default_publisher = 'pokemon-company'
+  config.default_game = 'pokemon-tcg'
+end
+
+# Search for games
+puts '=== Searching for Games ==='
+games = CardDB.games.search
+puts "Found #{games.total_count} games"
+games.each do |game|
+  puts "  - #{game.name} (#{game.key})"
+end
+
+# Search for datasets
+puts "\n=== Searching for Datasets ==="
+datasets = CardDB.datasets.search
+puts "Found #{datasets.total_count} datasets"
+datasets.each do |dataset|
+  puts "  - #{dataset.name} (#{dataset.key})"
+end
+
+# Get dataset schema
+puts "\n=== Dataset Schema ==="
+schema = CardDB.datasets.schema(dataset_key: 'cards')
+if schema
+  puts 'Fields:'
+  schema.fields.each do |field|
+    filterable = field.filterable? ? '[filterable]' : ''
+    searchable = field.searchable? ? '[searchable]' : ''
+    puts "  - #{field.key}: #{field.type} #{filterable} #{searchable}"
+  end
+end
+
+# Search for records
+puts "\n=== Searching for Records ==="
+records = CardDB.records.search(dataset_key: 'cards', first: 5)
+puts "Found #{records.total_count} records (showing first #{records.size})"
+records.each do |record|
+  puts "  - #{record['name']}"
+end
+
+# Search with filter DSL
+puts "\n=== Filtered Search (HP >= 100) ==="
+filtered = CardDB.records.search(dataset_key: 'cards', first: 5) do
+  where(hp: gte(100))
+end
+puts "Found #{filtered.total_count} records with HP >= 100"
+filtered.each do |record|
+  puts "  - #{record['name']} (HP: #{record['hp']})"
+end

data/examples/filtering.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'carddb'
+
+# Configure the client
+CardDB.configure do |config|
+  config.api_key = ENV.fetch('CARDDB_API_KEY', nil)
+  config.default_publisher = 'pokemon-company'
+  config.default_game = 'pokemon-tcg'
+end
+
+# Example 1: Simple equality
+puts '=== Simple Equality ==='
+records = CardDB.records.search(dataset_key: 'cards', first: 3) do
+  where(rarity: 'rare')
+end
+puts "Rare cards: #{records.total_count}"
+
+# Example 2: Comparison operators
+puts "\n=== Comparison Operators ==="
+records = CardDB.records.search(dataset_key: 'cards', first: 3) do
+  where(hp: gte(100))
+  where(hp: lte(150))
+end
+puts "Cards with HP 100-150: #{records.total_count}"
+
+# Example 3: Pattern matching
+puts "\n=== Pattern Matching ==="
+records = CardDB.records.search(dataset_key: 'cards', first: 3) do
+  where(name: ilike('%pikachu%'))
+end
+puts "Cards matching 'pikachu': #{records.total_count}"
+records.each { |r| puts "  - #{r['name']}" }
+
+# Example 4: Array contains
+puts "\n=== Array Contains ==="
+records = CardDB.records.search(dataset_key: 'cards', first: 3) do
+  where(types: contains('Pokemon'))
+end
+puts "Pokemon cards: #{records.total_count}"
+
+# Example 5: Value in list
+puts "\n=== Value in List ==="
+records = CardDB.records.search(dataset_key: 'cards', first: 3) do
+  where(rarity: within(%w[rare ultra-rare secret-rare]))
+end
+puts "Rare+ cards: #{records.total_count}"
+
+# Example 6: OR conditions
+puts "\n=== OR Conditions ==="
+records = CardDB.records.search(dataset_key: 'cards', first: 3) do
+  any do
+    where(hp: gte(200))
+    where(rarity: 'ultra-rare')
+  end
+end
+puts "High HP or Ultra Rare: #{records.total_count}"
+
+# Example 7: Complex filter
+puts "\n=== Complex Filter ==="
+records = CardDB.records.search(dataset_key: 'cards', first: 3) do
+  where(types: contains('Pokemon'))
+  where(hp: gte(100))
+  any do
+    where(rarity: 'rare')
+    where(rarity: 'ultra-rare')
+  end
+end
+puts "High HP rare Pokemon: #{records.total_count}"
+records.each { |r| puts "  - #{r['name']} (#{r['rarity']}, HP: #{r['hp']})" }
+
+# Example 8: Nested field filtering
+puts "\n=== Nested Fields ==="
+records = CardDB.records.search(dataset_key: 'cards', first: 3) do
+  where_any(:attacks, damage: gte(50))
+end
+puts "Cards with 50+ damage attacks: #{records.total_count}"
+
+# Example 9: Link filtering
+puts "\n=== Link Filtering ==="
+records = CardDB.records.search(
+  dataset_key: 'cards',
+  first: 3,
+  resolve_links: ['set_id']
+) do
+  where_link(:set_id, name: ilike('%scarlet%'))
+end
+puts "Cards from Scarlet sets: #{records.total_count}"
+records.each do |r|
+  set_name = r.resolved_links['set_id']&.record&.[]('name')
+  puts "  - #{r['name']} (Set: #{set_name})"
+end

data/examples/pagination.rb

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'carddb'
+
+# Configure the client
+CardDB.configure do |config|
+  config.api_key = ENV.fetch('CARDDB_API_KEY', nil)
+  config.default_publisher = 'pokemon-company'
+  config.default_game = 'pokemon-tcg'
+end
+
+# Example 1: Manual pagination
+puts '=== Manual Pagination ==='
+records = CardDB.records.search(dataset_key: 'cards', first: 10)
+puts "Total records: #{records.total_count}"
+puts "Page 1: #{records.size} records"
+
+page = 2
+while records.next_page?
+  records = records.next_page
+  puts "Page #{page}: #{records.size} records"
+  page += 1
+  break if page > 5 # Limit for demo
+end
+
+# Example 2: Auto-pagination with limit
+puts "\n=== Auto-Pagination (first 50) ==="
+count = 0
+CardDB.records.search(dataset_key: 'cards', first: 10)
+      .auto_paginate
+      .take(50)
+      .each do |record|
+  count += 1
+  puts "#{count}. #{record['name']}"
+end
+
+# Example 3: Collection metadata
+puts "\n=== Collection Metadata ==="
+records = CardDB.records.search(dataset_key: 'cards', first: 5)
+puts "Total count: #{records.total_count}"
+puts "Page size: #{records.size}"
+puts "Has next page: #{records.next_page?}"
+puts "Has previous page: #{records.previous_page?}"
+puts "End cursor: #{records.end_cursor}"
+
+# Example 4: Processing all records efficiently
+puts "\n=== Processing All Records ==="
+processed = 0
+CardDB.records.search(dataset_key: 'cards', first: 100)
+      .auto_paginate
+      .each do |_record|
+  # Process record
+  processed += 1
+  print "\rProcessed: #{processed} records" if (processed % 100).zero?
+  break if processed >= 500 # Limit for demo
+end
+puts "\nDone! Processed #{processed} records"

data/lib/carddb/batch.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module CardDB
+  # Batch query builder for combining multiple queries into a single request.
+  #
+  # @example
+  #   results = CardDB.batch do |b|
+  #     b.games.fetch("uuid-1")
+  #     b.games.fetch("uuid-2")
+  #     b.publishers.fetch(slug: "pokemon-company")
+  #   end
+  #
+  #   results[0]  # => Game
+  #   results[1]  # => Game
+  #   results[2]  # => Publisher
+  class Batch
+    # @return [Array<Hash>] The queued operations
+    attr_reader :operations
+
+    # @param client [Client] The client instance
+    def initialize(client)
+      @client = client
+      @operations = []
+      @counter = 0
+    end
+
+    # Access the Publishers resource for batching
+    #
+    # @return [BatchProxy]
+    def publishers
+      BatchProxy.new(self, :publishers)
+    end
+
+    # Access the Games resource for batching
+    #
+    # @return [BatchProxy]
+    def games
+      BatchProxy.new(self, :games)
+    end
+
+    # Access the Datasets resource for batching
+    #
+    # @return [BatchProxy]
+    def datasets
+      BatchProxy.new(self, :datasets)
+    end
+
+    # Access the Records resource for batching
+    #
+    # @return [BatchProxy]
+    def records
+      BatchProxy.new(self, :records)
+    end
+
+    # Add an operation to the batch
+    #
+    # @param resource [Symbol] The resource type
+    # @param method [Symbol] The method to call
+    # @param args [Array] Method arguments
+    # @param kwargs [Hash] Method keyword arguments
+    # @return [Integer] The index of this operation in the results
+    def add_operation(resource:, method:, args: [], kwargs: {})
+      @counter += 1
+      alias_name = "op#{@counter}"
+
+      @operations << {
+        alias: alias_name,
+        resource: resource,
+        method: method,
+        args: args,
+        kwargs: kwargs
+      }
+
+      @counter - 1
+    end
+
+    # Execute all batched operations
+    #
+    # @return [Array] Results in the same order as operations were added
+    def execute
+      return [] if @operations.empty?
+
+      # Build combined GraphQL query
+      query_parts = []
+      variables = {}
+
+      @operations.each_with_index do |op, index|
+        query_part, op_vars = build_operation_query(op, index)
+        query_parts << query_part
+        variables.merge!(op_vars)
+      end
+
+      # Combine into single query
+      var_definitions = build_variable_definitions(variables)
+      combined_query = <<~GRAPHQL
+        query BatchQuery#{var_definitions} {
+          #{query_parts.join("\n  ")}
+        }
+      GRAPHQL
+
+      # Execute the combined query
+      data = @client.connection.execute(combined_query, variables)
+
+      # Parse results
+      @operations.map do |op|
+        result = data[op[:alias]]
+        wrap_result(result, op[:resource], op[:method])
+      end
+    end
+
+    private
+
+    def build_operation_query(op, index)
+      case op[:resource]
+      when :publishers
+        build_publisher_query(op, index)
+      when :games
+        build_game_query(op, index)
+      when :datasets
+        build_dataset_query(op, index)
+      when :records
+        build_record_query(op, index)
+      else
+        raise ArgumentError, "Unknown resource: #{op[:resource]}"
+      end
+    end
+
+    def build_publisher_query(op, index)
+      case op[:method]
+      when :fetch
+        if op[:kwargs][:id]
+          var_name = "publisherId#{index}"
+          query = "#{op[:alias]}: fetchPublisher(id: $#{var_name}) { #{publisher_fields} }"
+          [query, { var_name => op[:kwargs][:id] }, { var_name => 'UUID' }]
+        else
+          var_name = "publisherSlug#{index}"
+          query = "#{op[:alias]}: fetchPublisher(slug: $#{var_name}) { #{publisher_fields} }"
+          [query, { var_name => op[:kwargs][:slug] }, { var_name => 'String' }]
+        end
+      else
+        raise ArgumentError, "Unsupported batch method for publishers: #{op[:method]}"
+      end
+    end
+
+    def build_game_query(op, index)
+      case op[:method]
+      when :fetch
+        var_name = "gameId#{index}"
+        query = "#{op[:alias]}: fetchGame(id: $#{var_name}) { #{game_fields} }"
+        [query, { var_name => op[:args][0] }, { var_name => 'UUID' }]
+      when :get
+        slug_var = "gamePublisherSlug#{index}"
+        key_var = "gameKey#{index}"
+        query = "#{op[:alias]}: fetchGame(publisherSlug: $#{slug_var}, gameKey: $#{key_var}) { #{game_fields} }"
+        resolved_publisher = @client.config.resolve_publisher(op[:kwargs][:publisher_slug])
+        [query, { slug_var => resolved_publisher, key_var => op[:kwargs][:game_key] },
+         { slug_var => 'String', key_var => 'String' }]
+      else
+        raise ArgumentError, "Unsupported batch method for games: #{op[:method]}"
+      end
+    end
+
+    def build_dataset_query(op, index)
+      case op[:method]
+      when :fetch
+        var_name = "datasetId#{index}"
+        query = "#{op[:alias]}: fetchDataset(id: $#{var_name}) { #{dataset_fields} }"
+        [query, { var_name => op[:args][0] }, { var_name => 'UUID' }]
+      when :get
+        slug_var = "datasetPublisherSlug#{index}"
+        game_var = "datasetGameKey#{index}"
+        key_var = "datasetKey#{index}"
+        query = "#{op[:alias]}: fetchDataset(publisherSlug: $#{slug_var}, gameKey: $#{game_var}, datasetKey: $#{key_var}) { #{dataset_fields} #{schema_fields} }"
+        resolved_publisher = @client.config.resolve_publisher(op[:kwargs][:publisher_slug])
+        resolved_game = @client.config.resolve_game(op[:kwargs][:game_key])
+        [query, { slug_var => resolved_publisher, game_var => resolved_game, key_var => op[:kwargs][:dataset_key] },
+         { slug_var => 'String', game_var => 'String', key_var => 'String' }]
+      else
+        raise ArgumentError, "Unsupported batch method for datasets: #{op[:method]}"
+      end
+    end
+
+    def build_record_query(op, index)
+      case op[:method]
+      when :fetch
+        var_name = "recordId#{index}"
+        query = "#{op[:alias]}: fetchRecord(id: $#{var_name}) { #{record_fields} }"
+        [query, { var_name => op[:args][0] }, { var_name => 'UUID' }]
+      when :get
+        slug_var = "recordPublisherSlug#{index}"
+        game_var = "recordGameKey#{index}"
+        dataset_var = "recordDatasetKey#{index}"
+        id_var = "recordIdentifier#{index}"
+        query = "#{op[:alias]}: fetchRecordByIdentifier(publisherSlug: $#{slug_var}, gameKey: $#{game_var}, datasetKey: $#{dataset_var}, identifier: $#{id_var}) { #{record_fields} }"
+        resolved_publisher = @client.config.resolve_publisher(op[:kwargs][:publisher_slug])
+        resolved_game = @client.config.resolve_game(op[:kwargs][:game_key])
+        [query,
+         { slug_var => resolved_publisher, game_var => resolved_game, dataset_var => op[:kwargs][:dataset_key], id_var => op[:kwargs][:identifier] }, { slug_var => 'String', game_var => 'String', dataset_var => 'String', id_var => 'String' }]
+      else
+        raise ArgumentError, "Unsupported batch method for records: #{op[:method]}"
+      end
+    end
+
+    def build_variable_definitions(variables)
+      return '' if variables.empty?
+
+      # Build type map from the operations
+      type_map = {}
+      @operations.each_with_index do |op, index|
+        _, _, types = build_operation_query(op, index)
+        type_map.merge!(types) if types
+      end
+
+      defs = variables.keys.map do |key|
+        type = type_map[key] || 'String'
+        "$#{key}: #{type}!"
+      end
+
+      "(#{defs.join(', ')})"
+    end
+
+    def wrap_result(result, resource, _method)
+      return nil if result.nil?
+
+      case resource
+      when :publishers
+        Publisher.new(result, client: @client)
+      when :games
+        Game.new(result, client: @client)
+      when :datasets
+        Dataset.new(result, client: @client)
+      when :records
+        Record.new(result, client: @client)
+      else
+        result
+      end
+    end
+
+    # Field definitions (simplified versions)
+    def publisher_fields
+      'id name slug status description website createdAt updatedAt logoFile { id url } bannerFile { id url }'
+    end
+
+    def game_fields
+      'id publisherId key name description website visibility isArchived createdAt updatedAt publisher { id name slug } logoFile { id url } coverFile { id url }'
+    end
+
+    def dataset_fields
+      'id publisherId gameId key name description visibility isArchived createdAt updatedAt publisher { id name slug } game { id key name }'
+    end
+
+    def schema_fields
+      [
+        'schema { fields {',
+        'key label description type isRequired filterable searchable isIdentifier',
+        'itemType displayFormat semanticType allowedValues',
+        '} filterableFields searchableFields linkFields {',
+        'key label targetDatasetKey targetDatasetName targetDatasetId',
+        '} }'
+      ].join(' ')
+    end
+
+    def record_fields
+      'id datasetId data createdAt updatedAt dataset { id key name gameId publisherId }'
+    end
+  end
+
+  # Proxy class for batching operations on a specific resource
+  class BatchProxy
+    def initialize(batch, resource)
+      @batch = batch
+      @resource = resource
+    end
+
+    # Proxy fetch calls to the batch
+    def fetch(*args, **kwargs)
+      @batch.add_operation(resource: @resource, method: :fetch, args: args, kwargs: kwargs)
+      nil # Return nil since we're batching
+    end
+
+    # Proxy get calls to the batch
+    def get(**kwargs)
+      @batch.add_operation(resource: @resource, method: :get, kwargs: kwargs)
+      nil # Return nil since we're batching
+    end
+  end
+end

data/lib/carddb/cache.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module CardDB
+  # Simple in-memory cache with TTL support.
+  # Compatible with Rails.cache interface (read/write/delete).
+  #
+  # @example
+  #   cache = CardDB::MemoryCache.new
+  #   cache.write("key", "value", expires_in: 60)
+  #   cache.read("key")  # => "value"
+  #   # After 60 seconds...
+  #   cache.read("key")  # => nil
+  class MemoryCache
+    def initialize
+      @store = {}
+      @mutex = Mutex.new
+    end
+
+    # Read a value from the cache.
+    #
+    # @param key [String] The cache key
+    # @return [Object, nil] The cached value or nil if not found/expired
+    def read(key)
+      @mutex.synchronize do
+        entry = @store[key]
+        return nil unless entry
+
+        if entry[:expires_at] && Time.now > entry[:expires_at]
+          @store.delete(key)
+          return nil
+        end
+
+        entry[:value]
+      end
+    end
+
+    # Write a value to the cache.
+    #
+    # @param key [String] The cache key
+    # @param value [Object] The value to cache
+    # @param expires_in [Integer, nil] TTL in seconds (nil = no expiry)
+    # @return [Object] The cached value
+    def write(key, value, expires_in: nil)
+      @mutex.synchronize do
+        expires_at = expires_in ? Time.now + expires_in : nil
+        @store[key] = { value: value, expires_at: expires_at }
+        value
+      end
+    end
+
+    # Delete a value from the cache.
+    #
+    # @param key [String] The cache key
+    # @return [Boolean] true if the key was deleted
+    def delete(key)
+      @mutex.synchronize do
+        !!@store.delete(key)
+      end
+    end
+
+    # Check if a key exists and is not expired.
+    #
+    # @param key [String] The cache key
+    # @return [Boolean]
+    def exist?(key)
+      !read(key).nil?
+    end
+
+    # Clear all cached values.
+    #
+    # @return [void]
+    def clear
+      @mutex.synchronize do
+        @store.clear
+      end
+    end
+
+    # Get the number of cached entries (for debugging).
+    #
+    # @return [Integer]
+    def size
+      @mutex.synchronize do
+        # Clean up expired entries first
+        now = Time.now
+        @store.delete_if { |_, entry| entry[:expires_at] && now > entry[:expires_at] }
+        @store.size
+      end
+    end
+  end
+
+  # Cache wrapper that provides a unified interface for caching.
+  # Supports any cache that responds to read/write (like Rails.cache).
+  #
+  # @example With built-in memory cache
+  #   CardDB.configure do |config|
+  #     config.cache = CardDB::MemoryCache.new
+  #     config.cache_ttl = 300  # 5 minutes
+  #   end
+  #
+  # @example With Rails.cache
+  #   CardDB.configure do |config|
+  #     config.cache = Rails.cache
+  #     config.cache_ttl = 300
+  #   end
+  #
+  # @example Disabling cache for a specific call
+  #   CardDB.games.fetch(id, cache: false)
+  module CacheSupport
+    # Generate a cache key for a query.
+    #
+    # @param resource [String] Resource type (publishers, games, etc.)
+    # @param method [String] Method name (fetch, get, search, etc.)
+    # @param params [Hash] Query parameters
+    # @return [String] The cache key
+    def self.cache_key(resource, method, params)
+      sorted_params = params.sort.map { |k, v| "#{k}=#{v}" }.join('&')
+      "carddb:#{resource}:#{method}:#{sorted_params}"
+    end
+  end
+end