carddb 0.2.0

data/lib/carddb/resources/base.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Base class for API resources
+    class Base
+      # @return [Client] The client instance
+      attr_reader :client
+
+      # @return [Connection] The API connection
+      attr_reader :connection
+
+      # @return [Configuration] The configuration
+      attr_reader :config
+
+      # @param client [Client] The client instance
+      # @param connection [Connection] The API connection
+      # @param config [Configuration] The configuration
+      def initialize(client, connection, config)
+        @client = client
+        @connection = connection
+        @config = config
+      end
+
+      private
+
+      # Resolve publisher slug, using default if not provided
+      def resolve_publisher(publisher_slug)
+        resolved = config.resolve_publisher(publisher_slug)
+        return resolved if resolved
+
+        raise ArgumentError, 'publisher_slug is required (no default configured)'
+      end
+
+      # Resolve game key, using default if not provided
+      def resolve_game(game_key)
+        resolved = config.resolve_game(game_key)
+        return resolved if resolved
+
+        raise ArgumentError, 'game_key is required (no default configured)'
+      end
+
+      # Validate access to publisher/game
+      def validate_access!(publisher_slug, game_key = nil)
+        config.validate_access!(publisher_slug, game_key)
+      end
+
+      # Build variables hash, removing nil values
+      def build_variables(**vars)
+        vars.compact
+      end
+
+      # Execute a query with optional caching.
+      #
+      # @param cache_key [String] The cache key
+      # @param resource [Symbol] The resource type for TTL lookup (:publishers, :games, :datasets, :records)
+      # @param cache [Boolean, nil] Whether to use cache (nil = use config default)
+      # @yield Block that executes the query and returns the result
+      # @return [Object] The result (from cache or fresh)
+      def with_cache(cache_key, resource:, cache: nil)
+        use_cache = cache.nil? ? config.cache : cache
+        return yield unless use_cache && config.cache
+
+        # Try to read from cache
+        cached = config.cache.read(cache_key)
+        return cached if cached
+
+        # Execute query and cache result with resource-specific TTL
+        result = yield
+        ttl = config.cache_ttl_for(resource)
+        config.cache.write(cache_key, result, expires_in: ttl) if result
+        result
+      end
+
+      # Generate a cache key for a resource operation.
+      #
+      # @param resource [String] Resource type
+      # @param method [String] Method name
+      # @param params [Hash] Parameters
+      # @return [String] The cache key
+      def cache_key(resource, method, **params)
+        CacheSupport.cache_key(resource, method, params)
+      end
+    end
+  end
+end

data/lib/carddb/resources/datasets.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Datasets resource for searching, fetching, and getting schema
+    class Datasets < Base
+      # Search for datasets
+      #
+      # @param publisher_slug [String, nil] Filter by publisher slug
+      # @param game_key [String, nil] Filter by game key
+      # @param search [String, nil] Search by name
+      # @param purpose [String, nil] Filter by dataset purpose (DATA or RULES)
+      # @param first [Integer, nil] Maximum number of results
+      # @param after [String, nil] Cursor for pagination
+      # @return [Collection<Dataset>] Collection of datasets
+      def search(publisher_slug: nil, game_key: nil, search: nil, purpose: nil, first: nil, after: nil)
+        resolved_publisher = config.resolve_publisher(publisher_slug)
+        resolved_game = config.resolve_game(game_key)
+
+        validate_access!(resolved_publisher, resolved_game) if resolved_publisher
+
+        query = QueryBuilder.search_datasets(
+          publisher_slug: resolved_publisher,
+          game_key: resolved_game,
+          search: search,
+          purpose: purpose,
+          first: first,
+          after: after
+        )
+
+        variables = build_variables(
+          publisherSlug: resolved_publisher,
+          gameKey: resolved_game,
+          search: search,
+          purpose: purpose,
+          first: first,
+          after: after
+        )
+
+        data = connection.execute(query, variables)
+
+        # Create next page loader
+        search_params = { publisher_slug: publisher_slug, game_key: game_key, search: search, purpose: purpose, first: first }
+        next_page_loader = ->(cursor) { search(**search_params, after: cursor) }
+
+        Collection.new(
+          data['searchDatasets'],
+          item_class: Dataset,
+          next_page_loader: next_page_loader,
+          client: client
+        )
+      end
+
+      # Fetch a dataset by ID (includes schema)
+      #
+      # @param id [String] The dataset UUID
+      # @param cache [Boolean, nil] Whether to cache (nil = use config setting)
+      # @return [Dataset, nil] The dataset or nil if not found
+      def fetch(id, cache: nil)
+        key = cache_key('datasets', 'fetch', id: id)
+        with_cache(key, resource: :datasets, cache: cache) do
+          query = QueryBuilder.fetch_dataset_by_id
+          data = connection.execute(query, { id: id })
+
+          return nil unless data['fetchDataset']
+
+          Dataset.new(data['fetchDataset'], client: client)
+        end
+      end
+
+      # Get a dataset by publisher/game/dataset keys (includes schema)
+      #
+      # @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 dataset_key [String] Dataset key (required)
+      # @param cache [Boolean, nil] Whether to cache (nil = use config setting)
+      # @return [Dataset, nil] The dataset or nil if not found
+      def get(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('datasets', 'get', publisher_slug: resolved_publisher, game_key: resolved_game,
+                                           dataset_key: dataset_key)
+        with_cache(key, resource: :datasets, cache: cache) do
+          query = QueryBuilder.fetch_dataset_by_keys
+          variables = {
+            publisherSlug: resolved_publisher,
+            gameKey: resolved_game,
+            datasetKey: dataset_key
+          }
+
+          data = connection.execute(query, variables)
+
+          return nil unless data['fetchDataset']
+
+          Dataset.new(data['fetchDataset'], client: client)
+        end
+      end
+
+      # Fetch multiple datasets by IDs
+      #
+      # @param ids [Array<String>] Array of dataset UUIDs (max 100)
+      # @return [Array<Dataset>] Array of datasets
+      # @raise [ArgumentError] If more than 100 IDs provided
+      def fetch_many(ids)
+        raise ArgumentError, 'Maximum 100 IDs allowed' if ids.length > 100
+
+        query = QueryBuilder.fetch_datasets
+        data = connection.execute(query, { ids: ids })
+
+        (data['fetchDatasets'] || []).map { |d| Dataset.new(d, client: client) }
+      end
+
+      # Get the schema for a dataset
+      #
+      # @param dataset_key [String] Dataset key
+      # @param publisher_slug [String, nil] Publisher slug (uses default if not provided)
+      # @param game_key [String, nil] Game key (uses default if not provided)
+      # @return [DatasetSchema, nil] The schema or nil if not found
+      def schema(dataset_key:, publisher_slug: nil, game_key: nil)
+        dataset = get(
+          dataset_key: dataset_key,
+          publisher_slug: publisher_slug,
+          game_key: game_key
+        )
+        dataset&.schema
+      end
+    end
+  end
+end

data/lib/carddb/resources/decks.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Decks resource for hosted decks and external deck hydration.
+    class Decks < Base
+      # List decks owned by the current account or API application.
+      def list_mine(first: nil, after: nil, cache: nil)
+        query = QueryBuilder.list_my_decks(first: first, after: after)
+        variables = build_variables(first: first, after: after)
+        key = cache_key('decks', 'list_mine', **variables)
+
+        data = with_cache(key, resource: :decks, cache: cache) do
+          connection.execute(query, variables)
+        end
+
+        Collection.new(
+          data['myDecks'],
+          item_class: Deck,
+          next_page_loader: ->(cursor) { list_mine(first: first, after: cursor, cache: cache) },
+          client: client
+        )
+      end
+
+      # Fetch a hosted deck by CardDB UUID.
+      def fetch(id, cache: nil)
+        key = cache_key('decks', 'fetch', id: id)
+        with_cache(key, resource: :decks, cache: cache) do
+          data = connection.execute(QueryBuilder.fetch_deck, { id: id })
+          data['fetchDeck'] ? Deck.new(data['fetchDeck'], client: client) : nil
+        end
+      end
+
+      # Fetch a hosted deck by external reference for the current API application.
+      def fetch_by_external_ref(external_ref:, cache: nil)
+        key = cache_key('decks', 'fetch_by_external_ref', external_ref: external_ref)
+        with_cache(key, resource: :decks, cache: cache) do
+          data = connection.execute(QueryBuilder.fetch_deck_by_external_ref, { externalRef: external_ref })
+          data['fetchDeckByExternalRef'] ? Deck.new(data['fetchDeckByExternalRef'], client: client) : nil
+        end
+      end
+
+      # Create a hosted deck.
+      def create(input:)
+        data = connection.execute(QueryBuilder.create_deck, { input: input })
+        Deck.new(data['deckCreate'], client: client)
+      end
+
+      # Update a hosted deck.
+      def update(id:, input:)
+        data = connection.execute(QueryBuilder.update_deck, { id: id, input: input })
+        Deck.new(data['deckUpdate'], client: client)
+      end
+
+      # Delete a hosted deck.
+      # rubocop:disable Naming/PredicateMethod
+      def delete(id:)
+        data = connection.execute(QueryBuilder.delete_deck, { id: id })
+        !!data['deckDelete']
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      # Hydrate third-party-owned deck entries without storing them in CardDB.
+      def hydrate_entries(dataset_key:, entries:, publisher_slug: nil, game_key: nil, identifier_field: nil, cache: nil)
+        return [] if entries.empty?
+
+        resolved_publisher = resolve_publisher(publisher_slug)
+        resolved_game = resolve_game(game_key)
+        validate_access!(resolved_publisher, resolved_game)
+
+        identifiers = entries.map { |entry| entry_identifier(entry) }
+        key = cache_key(
+          'decks',
+          'hydrate_entries',
+          publisher_slug: resolved_publisher,
+          game_key: resolved_game,
+          dataset_key: dataset_key,
+          identifiers: identifiers
+        )
+        records = with_cache(key, resource: :decks, cache: cache) do
+          data = connection.execute(
+            QueryBuilder.fetch_records_by_identifier,
+            {
+              publisherSlug: resolved_publisher,
+              gameKey: resolved_game,
+              datasetKey: dataset_key,
+              identifiers: identifiers
+            }
+          )
+          (data['fetchRecordsByIdentifier'] || []).map { |record| Record.new(record, client: client) }
+        end
+
+        records_by_identifier = records_by_deck_identifier(records, identifiers, identifier_field)
+        entries.map do |entry|
+          entry.merge(record: records_by_identifier[entry_identifier(entry)])
+        end
+      end
+
+      private
+
+      def entry_identifier(entry)
+        entry[:identifier] || entry['identifier'] || raise(ArgumentError, 'entry identifier is required')
+      end
+
+      def records_by_deck_identifier(records, identifiers, identifier_field)
+        remaining = identifiers.to_h { |identifier| [identifier.to_s, true] }
+        records.each_with_object({}) do |record, hash|
+          identifier = deck_record_identifier(record, remaining, identifier_field)
+          next unless identifier
+
+          key = identifier.to_s
+          next unless remaining.delete(key)
+
+          hash[key] = record
+        end
+      end
+
+      def deck_record_identifier(record, remaining, identifier_field)
+        return record[identifier_field] if identifier_field
+
+        record.record_data&.values&.find { |value| remaining[value.to_s] }
+      end
+    end
+  end
+end

data/lib/carddb/resources/games.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Games resource for searching and fetching games
+    class Games < Base
+      # Search for games
+      #
+      # @param publisher_slug [String, nil] Filter by publisher slug
+      # @param search [String, nil] Search by name
+      # @param first [Integer, nil] Maximum number of results
+      # @param after [String, nil] Cursor for pagination
+      # @return [Collection<Game>] Collection of games
+      def search(publisher_slug: nil, search: nil, first: nil, after: nil)
+        resolved_publisher = config.resolve_publisher(publisher_slug)
+        validate_access!(resolved_publisher, nil) if resolved_publisher
+
+        query = QueryBuilder.search_games(
+          publisher_slug: resolved_publisher,
+          search: search,
+          first: first,
+          after: after
+        )
+
+        variables = build_variables(
+          publisherSlug: resolved_publisher,
+          search: search,
+          first: first,
+          after: after
+        )
+
+        data = connection.execute(query, variables)
+
+        # Create next page loader
+        next_page_loader = lambda do |cursor|
+          search(
+            publisher_slug: publisher_slug,
+            search: search,
+            first: first,
+            after: cursor
+          )
+        end
+
+        Collection.new(
+          data['searchGames'],
+          item_class: Game,
+          next_page_loader: next_page_loader,
+          client: client
+        )
+      end
+
+      # Fetch a game by ID
+      #
+      # @param id [String] The game UUID
+      # @param cache [Boolean, nil] Whether to cache (nil = use config setting)
+      # @return [Game, nil] The game or nil if not found
+      def fetch(id, cache: nil)
+        key = cache_key('games', 'fetch', id: id)
+        with_cache(key, resource: :games, cache: cache) do
+          query = QueryBuilder.fetch_game_by_id
+          data = connection.execute(query, { id: id })
+
+          return nil unless data['fetchGame']
+
+          Game.new(data['fetchGame'], client: client)
+        end
+      end
+
+      # Get a game by publisher slug and game key
+      #
+      # @param game_key [String] Game key (required)
+      # @param publisher_slug [String, nil] Publisher slug (uses default if not provided)
+      # @param cache [Boolean, nil] Whether to cache (nil = use config setting)
+      # @return [Game, nil] The game or nil if not found
+      def get(game_key:, publisher_slug: nil, cache: nil)
+        resolved_publisher = resolve_publisher(publisher_slug)
+
+        validate_access!(resolved_publisher, game_key)
+
+        key = cache_key('games', 'get', publisher_slug: resolved_publisher, game_key: game_key)
+        with_cache(key, resource: :games, cache: cache) do
+          query = QueryBuilder.fetch_game_by_keys
+          variables = {
+            publisherSlug: resolved_publisher,
+            gameKey: game_key
+          }
+
+          data = connection.execute(query, variables)
+
+          return nil unless data['fetchGame']
+
+          Game.new(data['fetchGame'], client: client)
+        end
+      end
+
+      # Fetch multiple games by IDs
+      #
+      # @param ids [Array<String>] Array of game UUIDs (max 100)
+      # @return [Array<Game>] Array of games
+      # @raise [ArgumentError] If more than 100 IDs provided
+      def fetch_many(ids)
+        raise ArgumentError, 'Maximum 100 IDs allowed' if ids.length > 100
+
+        query = QueryBuilder.fetch_games
+        data = connection.execute(query, { ids: ids })
+
+        (data['fetchGames'] || []).map { |g| Game.new(g, client: client) }
+      end
+    end
+  end
+end

data/lib/carddb/resources/publishers.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Publishers resource for searching and fetching publishers
+    class Publishers < Base
+      # Search for publishers
+      #
+      # @param search [String, nil] Search by name
+      # @param first [Integer, nil] Maximum number of results
+      # @param after [String, nil] Cursor for pagination
+      # @return [Collection<Publisher>] Collection of publishers
+      def search(search: nil, first: nil, after: nil)
+        query = QueryBuilder.search_publishers(
+          search: search,
+          first: first,
+          after: after
+        )
+
+        variables = build_variables(
+          search: search,
+          first: first,
+          after: after
+        )
+
+        data = connection.execute(query, variables)
+
+        # Create next page loader
+        next_page_loader = lambda do |cursor|
+          search(
+            search: search,
+            first: first,
+            after: cursor
+          )
+        end
+
+        Collection.new(
+          data['searchPublishers'],
+          item_class: Publisher,
+          next_page_loader: next_page_loader,
+          client: client
+        )
+      end
+
+      # Fetch a publisher by ID or slug
+      #
+      # @param id [String, nil] The publisher UUID
+      # @param slug [String, nil] The publisher slug
+      # @param cache [Boolean, nil] Whether to cache (nil = use config setting)
+      # @return [Publisher, nil] The publisher or nil if not found
+      # @raise [ArgumentError] If neither id nor slug is provided
+      def fetch(id: nil, slug: nil, cache: nil)
+        raise ArgumentError, 'Must provide either id or slug' if id.nil? && slug.nil?
+
+        key = cache_key('publishers', 'fetch', id: id, slug: slug)
+        with_cache(key, resource: :publishers, cache: cache) do
+          if id
+            query = QueryBuilder.fetch_publisher_by_id
+            data = connection.execute(query, { id: id })
+          else
+            query = QueryBuilder.fetch_publisher_by_slug
+            data = connection.execute(query, { slug: slug })
+          end
+
+          return nil unless data['fetchPublisher']
+
+          Publisher.new(data['fetchPublisher'], client: client)
+        end
+      end
+
+      # Fetch multiple publishers by slugs
+      #
+      # @param slugs [Array<String>] Array of publisher slugs (max 100)
+      # @return [Array<Publisher>] Array of publishers
+      # @raise [ArgumentError] If more than 100 slugs provided
+      def fetch_many(slugs)
+        raise ArgumentError, 'Maximum 100 slugs allowed' if slugs.length > 100
+
+        query = QueryBuilder.fetch_publishers
+        data = connection.execute(query, { slugs: slugs })
+
+        (data['fetchPublishers'] || []).map { |p| Publisher.new(p, client: client) }
+      end
+    end
+  end
+end