carddb 0.2.0

data/lib/carddb/resources/records.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Records resource for searching and fetching records
+    class Records < Base
+      include FilterOperators
+
+      # Search for records in a dataset
+      #
+      # @param dataset_key [String] Dataset key (required)
+      # @param publisher_slug [String, nil] Publisher slug (uses default if not provided)
+      # @param game_key [String, nil] Game key (uses default if not provided)
+      # @param filter [Hash, nil] Filter conditions
+      # @param search [String, nil] Full-text search
+      # @param order_by [String, nil] Field to order by (e.g., "name:asc")
+      # @param resolve_links [Array<String>, nil] Link fields to resolve
+      # @param first [Integer, nil] Maximum number of results
+      # @param after [String, nil] Cursor for pagination
+      # @param validate_schema [Boolean, nil] Whether to validate against schema
+      # @yield [FilterBuilder] Optional block for filter DSL
+      # @return [Collection<Record>] Collection of records
+      #
+      # @example Basic search
+      #   records = client.records.search(dataset_key: "cards")
+      #
+      # @example With filter DSL
+      #   records = client.records.search(dataset_key: "cards") do
+      #     where(type: "creature")
+      #     where(hp: gte(100))
+      #   end
+      #
+      # @example With hash filter
+      #   records = client.records.search(
+      #     dataset_key: "cards",
+      #     filter: { "type" => "creature" }
+      #   )
+      # rubocop:disable Metrics/MethodLength
+      def search(
+        dataset_key:,
+        publisher_slug: nil,
+        game_key: nil,
+        filter: nil,
+        search: nil,
+        order_by: nil,
+        resolve_links: nil,
+        first: nil,
+        after: nil,
+        validate_schema: nil,
+        &block
+      )
+        resolved_publisher = resolve_publisher(publisher_slug)
+        resolved_game = resolve_game(game_key)
+
+        validate_access!(resolved_publisher, resolved_game)
+
+        # Build filter from DSL block if provided
+        final_filter = if block_given?
+                         FilterBuilder.build(&block)
+                       else
+                         filter
+                       end
+
+        query = QueryBuilder.search_records(
+          publisher_slug: resolved_publisher,
+          game_key: resolved_game,
+          dataset_key: dataset_key,
+          filter: final_filter,
+          search: search,
+          order_by: order_by,
+          resolve_links: resolve_links,
+          first: first,
+          after: after,
+          validate_schema: validate_schema
+        )
+
+        variables = build_variables(
+          publisherSlug: resolved_publisher,
+          gameKey: resolved_game,
+          datasetKey: dataset_key,
+          filter: final_filter,
+          search: search,
+          orderBy: order_by,
+          resolveLinks: resolve_links,
+          first: first,
+          after: after,
+          validateSchema: validate_schema
+        )
+
+        data = connection.execute(query, variables)
+
+        # Create next page loader that preserves the filter block
+        search_params = {
+          dataset_key: dataset_key,
+          publisher_slug: publisher_slug,
+          game_key: game_key,
+          filter: final_filter,
+          search: search,
+          order_by: order_by,
+          resolve_links: resolve_links,
+          first: first,
+          validate_schema: validate_schema
+        }
+
+        next_page_loader = lambda do |cursor|
+          search(**search_params, after: cursor)
+        end
+
+        Collection.new(
+          data['searchRecords'],
+          item_class: Record,
+          next_page_loader: next_page_loader,
+          client: client
+        )
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Fetch a single record by ID
+      #
+      # @param id [String] The record UUID
+      # @param cache [Boolean, nil] Whether to cache (nil = use config setting)
+      # @return [Record, nil] The record or nil if not found
+      def fetch(id, cache: nil)
+        key = cache_key('records', 'fetch', id: id)
+        with_cache(key, resource: :records, cache: cache) do
+          query = QueryBuilder.fetch_record
+          data = connection.execute(query, { id: id })
+
+          return nil unless data['fetchRecord']
+
+          Record.new(data['fetchRecord'], client: client)
+        end
+      end
+
+      # Get a record by its identifier value
+      #
+      # Looks up the record using the dataset's designated identifier field.
+      # Returns nil if the dataset has no identifier field or if no matching record is found.
+      #
+      # @param identifier [String] The identifier value to look up
+      # @param dataset_key [String] Dataset key (required)
+      # @param publisher_slug [String, nil] Publisher slug (uses default if not provided)
+      # @param game_key [String, nil] Game key (uses default if not provided)
+      # @param cache [Boolean, nil] Whether to cache (nil = use config setting)
+      # @return [Record, nil] The record or nil if not found
+      #
+      # @example
+      #   record = client.records.get(identifier: "xy1-1", dataset_key: "cards")
+      def get(identifier:, dataset_key:, publisher_slug: nil, game_key: nil, cache: nil)
+        resolved_publisher = resolve_publisher(publisher_slug)
+        resolved_game = resolve_game(game_key)
+
+        validate_access!(resolved_publisher, resolved_game)
+
+        key = cache_key('records', 'get', publisher_slug: resolved_publisher, game_key: resolved_game,
+                                          dataset_key: dataset_key, identifier: identifier)
+        with_cache(key, resource: :records, cache: cache) do
+          query = QueryBuilder.fetch_record_by_identifier
+          variables = {
+            publisherSlug: resolved_publisher,
+            gameKey: resolved_game,
+            datasetKey: dataset_key,
+            identifier: identifier
+          }
+
+          data = connection.execute(query, variables)
+
+          return nil unless data['fetchRecordByIdentifier']
+
+          Record.new(data['fetchRecordByIdentifier'], client: client)
+        end
+      end
+
+      # Get multiple records by their identifier values
+      #
+      # Looks up records using the dataset's designated identifier field.
+      # Missing identifiers are omitted from the result.
+      #
+      # @param identifiers [Array<String>] Identifier values to look up (max 1000)
+      # @param dataset_key [String] Dataset key (required)
+      # @param publisher_slug [String, nil] Publisher slug (uses default if not provided)
+      # @param game_key [String, nil] Game key (uses default if not provided)
+      # @param cache [Boolean, nil] Whether to cache (nil = use config setting)
+      # @return [Array<Record>] Matching records
+      # @raise [ArgumentError] If more than 1000 identifiers are provided
+      #
+      # @example
+      #   records = client.records.get_many(
+      #     identifiers: ["xy1-1", "xy1-2"],
+      #     dataset_key: "cards"
+      #   )
+      def get_many(identifiers:, dataset_key:, publisher_slug: nil, game_key: nil, cache: nil)
+        raise ArgumentError, 'Maximum 1000 identifiers allowed' if identifiers.length > 1000
+        return [] if identifiers.empty?
+
+        resolved_publisher = resolve_publisher(publisher_slug)
+        resolved_game = resolve_game(game_key)
+
+        validate_access!(resolved_publisher, resolved_game)
+
+        key = cache_key(
+          'records',
+          'get_many',
+          publisher_slug: resolved_publisher,
+          game_key: resolved_game,
+          dataset_key: dataset_key,
+          identifiers: identifiers
+        )
+        with_cache(key, resource: :records, cache: cache) do
+          query = QueryBuilder.fetch_records_by_identifier
+          variables = {
+            publisherSlug: resolved_publisher,
+            gameKey: resolved_game,
+            datasetKey: dataset_key,
+            identifiers: identifiers
+          }
+
+          data = connection.execute(query, variables)
+
+          (data['fetchRecordsByIdentifier'] || []).map { |record| Record.new(record, client: client) }
+        end
+      end
+
+      # Fetch multiple records by IDs
+      #
+      # @param ids [Array<String>] Array of record UUIDs (max 1000)
+      # @return [Array<Record>] Array of records
+      # @raise [ArgumentError] If more than 1000 IDs provided
+      def fetch_many(ids)
+        raise ArgumentError, 'Maximum 1000 IDs allowed' if ids.length > 1000
+
+        query = QueryBuilder.fetch_records
+        data = connection.execute(query, { ids: ids })
+
+        (data['fetchRecords'] || []).map { |r| Record.new(r, client: client) }
+      end
+    end
+  end
+end

data/lib/carddb/resources/rules.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Rules resource for listing game rules and deck formats.
+    class Rules < Base
+      # List rule-related datasets for a game.
+      #
+      # @param publisher_slug [String, nil] Publisher slug (uses default if not provided)
+      # @param game_key [String, nil] Game key (uses default if not provided)
+      # @param search [String, nil] Search by dataset name
+      # @param first [Integer, nil] Maximum number of results
+      # @param after [String, nil] Cursor for pagination
+      # @return [Collection<Dataset>] Collection of rule datasets
+      def datasets(publisher_slug: nil, game_key: nil, search: nil, first: nil, after: nil)
+        client.datasets.search(
+          publisher_slug: publisher_slug,
+          game_key: game_key,
+          search: search,
+          purpose: 'RULES',
+          first: first,
+          after: after
+        )
+      end
+
+      # List rules from the game's rules dataset.
+      #
+      # @param dataset_key [String] Rules dataset key (defaults to "rules")
+      # @return [Collection<Record>] Collection of rule records
+      def list(dataset_key: 'rules', **options, &block)
+        search_records(dataset_key: dataset_key, **options, &block)
+      end
+
+      # List deck/game formats from the game's formats dataset.
+      #
+      # @param dataset_key [String] Formats dataset key (defaults to "formats")
+      # @return [Collection<Record>] Collection of format records
+      def formats(dataset_key: 'formats', **options, &block)
+        search_records(dataset_key: dataset_key, **options, &block)
+      end
+
+      private
+
+      def search_records(dataset_key:, **options, &block)
+        client.records.search(dataset_key: dataset_key, **options, &block)
+      end
+    end
+  end
+end

data/lib/carddb/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CardDB
+  VERSION = '0.2.0'
+end

data/lib/carddb.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative 'carddb/version'
+require_relative 'carddb/errors'
+require_relative 'carddb/configuration'
+require_relative 'carddb/connection'
+require_relative 'carddb/query_builder'
+require_relative 'carddb/filter_builder'
+require_relative 'carddb/collection'
+require_relative 'carddb/cache'
+require_relative 'carddb/resources/base'
+require_relative 'carddb/resources/publishers'
+require_relative 'carddb/resources/games'
+require_relative 'carddb/resources/datasets'
+require_relative 'carddb/resources/records'
+require_relative 'carddb/resources/decks'
+require_relative 'carddb/resources/rules'
+require_relative 'carddb/batch'
+require_relative 'carddb/client'
+
+# CardDB Ruby client library.
+#
+# A Ruby client for the CardDB GraphQL API, providing search and fetch
+# operations for card game data.
+#
+# @example Configure globally
+#   CardDB.configure do |config|
+#     config.api_key = "carddb_xxx"
+#     config.default_publisher = "pokemon-company"
+#     config.default_game = "pokemon-tcg"
+#   end
+#
+# @example Use module-level convenience methods
+#   games = CardDB.games.search
+#   records = CardDB.records.search(dataset_key: "cards")
+#
+# @example Use a dedicated client instance
+#   client = CardDB::Client.new(api_key: "carddb_xxx")
+#   games = client.games.search
+module CardDB
+  class << self
+    # @return [Configuration] Global configuration instance
+    attr_writer :configuration
+
+    # Get the global configuration.
+    #
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure the CardDB client globally.
+    #
+    # @yield [Configuration] The configuration instance
+    # @return [Configuration]
+    #
+    # @example
+    #   CardDB.configure do |config|
+    #     config.api_key = "carddb_xxx"
+    #     config.default_publisher = "pokemon-company"
+    #   end
+    def configure
+      # Reset the cached client so it picks up new configuration
+      @default_client = nil
+      yield(configuration)
+      configuration
+    end
+
+    # Reset the global configuration to defaults.
+    #
+    # @return [Configuration]
+    def reset_configuration!
+      @configuration = Configuration.new
+      @default_client = nil
+      configuration
+    end
+
+    # Get the default client instance (uses global configuration).
+    #
+    # @return [Client]
+    def default_client
+      @default_client ||= Client.new(config: configuration)
+    end
+
+    # Access the Publishers resource via the default client.
+    #
+    # @return [Resources::Publishers]
+    def publishers
+      default_client.publishers
+    end
+
+    # Access the Games resource via the default client.
+    #
+    # @return [Resources::Games]
+    def games
+      default_client.games
+    end
+
+    # Access the Datasets resource via the default client.
+    #
+    # @return [Resources::Datasets]
+    def datasets
+      default_client.datasets
+    end
+
+    # Access the Records resource via the default client.
+    #
+    # @return [Resources::Records]
+    def records
+      default_client.records
+    end
+
+    # Access the Decks resource via the default client.
+    #
+    # @return [Resources::Decks]
+    def decks
+      default_client.decks
+    end
+
+    # Access the Rules resource via the default client.
+    #
+    # @return [Resources::Rules]
+    def rules
+      default_client.rules
+    end
+
+    # Get information about the current API key.
+    #
+    # @return [Hash, nil]
+    def me
+      default_client.me
+    end
+
+    # Get the last rate limit info from the most recent request.
+    #
+    # @return [Hash, nil] Rate limit info with :limit, :remaining, :reset keys
+    def rate_limit_info
+      Thread.current[:carddb_rate_limit]
+    end
+
+    # Execute multiple queries in a single batch request.
+    #
+    # @yield [Batch] The batch builder
+    # @return [Array] Results in the same order as operations were added
+    #
+    # @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
+    def batch(&block)
+      default_client.batch(&block)
+    end
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: carddb
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- CardDB Team
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A Ruby client library for interacting with the CardDB GraphQL API. Search
+  and fetch card game data with an expressive filter DSL.
+email:
+- support@carddb.xtda.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rspec_status"
+- ".rubocop.yml"
+- AGENTS.md
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/basic_usage.rb
+- examples/filtering.rb
+- examples/pagination.rb
+- lib/carddb.rb
+- lib/carddb/batch.rb
+- lib/carddb/cache.rb
+- lib/carddb/client.rb
+- lib/carddb/collection.rb
+- lib/carddb/configuration.rb
+- lib/carddb/connection.rb
+- lib/carddb/errors.rb
+- lib/carddb/filter_builder.rb
+- lib/carddb/query_builder.rb
+- lib/carddb/resources/base.rb
+- lib/carddb/resources/datasets.rb
+- lib/carddb/resources/decks.rb
+- lib/carddb/resources/games.rb
+- lib/carddb/resources/publishers.rb
+- lib/carddb/resources/records.rb
+- lib/carddb/resources/rules.rb
+- lib/carddb/version.rb
+homepage: https://github.com/xtda/carddb-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/xtda/carddb-ruby
+  source_code_uri: https://github.com/xtda/carddb-ruby
+  changelog_uri: https://github.com/xtda/carddb-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: Ruby client for the CardDB API
+test_files: []