carddb 0.2.0

data/lib/carddb/collection.rb

@@ -0,0 +1,919 @@
+# frozen_string_literal: true
+
+module CardDB
+  # Represents a paginated collection of results from the API.
+  # Implements Enumerable for easy iteration.
+  class Collection
+    include Enumerable
+
+    # @return [Integer] Total count of matching records
+    attr_reader :total_count
+
+    # @return [Hash] Page info with cursor data
+    attr_reader :page_info
+
+    # @return [Array] The items in this page
+    attr_reader :items
+
+    # @return [Proc, nil] Proc to fetch the next page
+    attr_reader :next_page_loader
+
+    # @param data [Hash] The connection data from GraphQL response
+    # @param item_class [Class, nil] Optional class to wrap items
+    # @param next_page_loader [Proc, nil] Proc to load next page
+    # @param client [Client, nil] Client instance for making related queries
+    def initialize(data, item_class: nil, next_page_loader: nil, client: nil)
+      @total_count = data['totalCount']
+      @page_info = PageInfo.new(data['pageInfo']) if data['pageInfo']
+      @items = parse_items(data['edges'] || [], item_class, client)
+      @next_page_loader = next_page_loader
+    end
+
+    # Iterate over items
+    def each(&block)
+      items.each(&block)
+    end
+
+    # Check if there are more pages
+    #
+    # @return [Boolean]
+    def next_page?
+      page_info&.has_next_page || false
+    end
+
+    # Check if there are previous pages
+    #
+    # @return [Boolean]
+    def previous_page?
+      page_info&.has_previous_page || false
+    end
+
+    # Get the cursor for the next page
+    #
+    # @return [String, nil]
+    def end_cursor
+      page_info&.end_cursor
+    end
+
+    # Get the cursor for the previous page
+    #
+    # @return [String, nil]
+    def start_cursor
+      page_info&.start_cursor
+    end
+
+    # Fetch the next page of results
+    #
+    # @return [Collection, nil] The next page, or nil if no more pages
+    # @raise [CardDB::Error] If no next page loader is configured
+    def next_page
+      return nil unless next_page?
+      raise Error, 'No next page loader configured' unless next_page_loader
+
+      next_page_loader.call(end_cursor)
+    end
+
+    # Returns a lazy enumerator that auto-paginates through all results.
+    #
+    # @return [Enumerator::Lazy]
+    def auto_paginate
+      Enumerator.new do |yielder|
+        current = self
+        loop do
+          current.each { |item| yielder << item }
+          break unless current.next_page?
+
+          current = current.next_page
+          break if current.nil?
+        end
+      end.lazy
+    end
+
+    # Iterates through all results, automatically paginating as needed.
+    # Similar to ActiveRecord's find_each.
+    #
+    # @param batch_size [Integer] Number of records per API request (default: 100, max: 100)
+    # @yield [item] Each item in the collection
+    # @return [void]
+    #
+    # @example
+    #   collection.find_each do |record|
+    #     puts record.name
+    #   end
+    #
+    # @example With custom batch size
+    #   collection.find_each(batch_size: 50) do |record|
+    #     process(record)
+    #   end
+    def find_each(batch_size: 100, &block)
+      return enum_for(:find_each, batch_size: batch_size) unless block_given?
+
+      find_in_batches(batch_size: batch_size) do |batch|
+        batch.each(&block)
+      end
+    end
+
+    # Yields batches of records, automatically paginating as needed.
+    # Similar to ActiveRecord's find_in_batches.
+    #
+    # @param batch_size [Integer] Number of records per batch/API request (default: 100, max: 100)
+    # @yield [batch] Array of items for each batch
+    # @return [void]
+    #
+    # @example
+    #   collection.find_in_batches(batch_size: 50) do |batch|
+    #     batch.each { |record| process(record) }
+    #   end
+    def find_in_batches(batch_size: 100)
+      return enum_for(:find_in_batches, batch_size: batch_size) unless block_given?
+
+      # Clamp batch_size to valid range
+      [[batch_size, 1].max, 100].min
+
+      # For the first batch, we use the items already loaded
+      # (they may have been fetched with a different page size, but that's ok)
+      current = self
+
+      loop do
+        # Yield the current page's items
+        yield current.items unless current.items.empty?
+
+        # Stop if no more pages
+        break unless current.next_page?
+
+        # Fetch next page with the specified batch_size
+        # Note: The next_page_loader uses the original 'first' parameter,
+        # but subsequent pages will use the original size.
+        # To truly control batch_size, we'd need to modify the loader.
+        current = current.next_page
+        break if current.nil?
+      end
+    end
+
+    # Get number of items in current page
+    #
+    # @return [Integer]
+    def size
+      items.size
+    end
+    alias length size
+
+    # Check if collection is empty
+    #
+    # @return [Boolean]
+    def empty?
+      items.empty?
+    end
+
+    # Get first item
+    #
+    # @return [Object, nil]
+    def first
+      items.first
+    end
+
+    # Get last item
+    #
+    # @return [Object, nil]
+    def last
+      items.last
+    end
+
+    private
+
+    def parse_items(edges, item_class, client)
+      edges.map do |edge|
+        node = edge['node']
+        if item_class
+          item_class.new(node, client: client)
+        else
+          node
+        end
+      end
+    end
+  end
+
+  # Represents pagination info
+  class PageInfo
+    # @return [Boolean]
+    attr_reader :has_next_page
+
+    # @return [Boolean]
+    attr_reader :has_previous_page
+
+    # @return [String, nil]
+    attr_reader :start_cursor
+
+    # @return [String, nil]
+    attr_reader :end_cursor
+
+    def initialize(data)
+      @has_next_page = data['hasNextPage'] || false
+      @has_previous_page = data['hasPreviousPage'] || false
+      @start_cursor = data['startCursor']
+      @end_cursor = data['endCursor']
+    end
+  end
+
+  # Base class for resource wrappers
+  class Resource
+    # @return [Hash] The raw data from the API
+    attr_reader :data
+
+    # @return [Client, nil] The client instance for making related queries
+    attr_reader :client
+
+    def initialize(data, client: nil)
+      @data = data || {}
+      @client = client
+    end
+
+    # Access raw data fields
+    def [](key)
+      data[key.to_s]
+    end
+
+    # Check if a field exists
+    def key?(key)
+      data.key?(key.to_s)
+    end
+
+    def to_h
+      data
+    end
+
+    def to_json(*args)
+      data.to_json(*args)
+    end
+  end
+
+  # Wrapper for Publisher objects
+  class Publisher < Resource
+    def id
+      data['id']
+    end
+
+    def name
+      data['name']
+    end
+
+    def slug
+      data['slug']
+    end
+
+    def description
+      data['description']
+    end
+
+    def website
+      data['website']
+    end
+
+    # @return [String] Publisher status (`ACTIVE` or `DEACTIVATED`)
+    def status
+      data['status']
+    end
+
+    def logo_url
+      data.dig('logoFile', 'url')
+    end
+
+    def banner_url
+      data.dig('bannerFile', 'url')
+    end
+
+    def created_at
+      parse_time(data['createdAt'])
+    end
+
+    def updated_at
+      parse_time(data['updatedAt'])
+    end
+
+    # Fetch games belonging to this publisher.
+    # Results are cached after the first call.
+    #
+    # @return [Collection<Game>] Collection of games
+    # @raise [CardDB::Error] If no client is available
+    def games
+      @games ||= fetch_games
+    end
+
+    private
+
+    def fetch_games
+      raise Error, 'No client available to fetch games' unless client
+
+      client.games.search(publisher_slug: slug)
+    end
+
+    def parse_time(value)
+      return nil unless value
+
+      Time.parse(value)
+    rescue ArgumentError
+      value
+    end
+  end
+
+  # Wrapper for Game objects
+  class Game < Resource
+    def id
+      data['id']
+    end
+
+    def key
+      data['key']
+    end
+
+    def name
+      data['name']
+    end
+
+    def description
+      data['description']
+    end
+
+    def website
+      data['website']
+    end
+
+    def visibility
+      data['visibility']
+    end
+
+    def archived?
+      data['isArchived']
+    end
+
+    def publisher_id
+      data['publisherId']
+    end
+
+    def publisher
+      data['publisher']
+    end
+
+    def logo_url
+      data.dig('logoFile', 'url')
+    end
+
+    def cover_url
+      data.dig('coverFile', 'url')
+    end
+
+    def created_at
+      parse_time(data['createdAt'])
+    end
+
+    def updated_at
+      parse_time(data['updatedAt'])
+    end
+
+    # Fetch datasets belonging to this game.
+    # Unfiltered results are cached after the first call.
+    #
+    # @param purpose [String, nil] Filter by dataset purpose (DATA or RULES)
+    # @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 datasets
+    # @raise [CardDB::Error] If no client is available
+    def datasets(purpose: nil, search: nil, first: nil, after: nil)
+      if purpose.nil? && search.nil? && first.nil? && after.nil?
+        @datasets ||= fetch_datasets
+      else
+        fetch_datasets(purpose: purpose, search: search, first: first, after: after)
+      end
+    end
+
+    private
+
+    def fetch_datasets(purpose: nil, search: nil, first: nil, after: nil)
+      raise Error, 'No client available to fetch datasets' unless client
+
+      publisher_slug = publisher&.[]('slug')
+      raise Error, 'Publisher slug not available on this game' unless publisher_slug
+
+      client.datasets.search(
+        publisher_slug: publisher_slug,
+        game_key: key,
+        search: search,
+        purpose: purpose,
+        first: first,
+        after: after
+      )
+    end
+
+    def parse_time(value)
+      return nil unless value
+
+      Time.parse(value)
+    rescue ArgumentError
+      value
+    end
+  end
+
+  # Wrapper for Dataset objects
+  class Dataset < Resource
+    def id
+      data['id']
+    end
+
+    def key
+      data['key']
+    end
+
+    def name
+      data['name']
+    end
+
+    def description
+      data['description']
+    end
+
+    def purpose
+      data['purpose']
+    end
+
+    def visibility
+      data['visibility']
+    end
+
+    def archived?
+      data['isArchived']
+    end
+
+    def publisher_id
+      data['publisherId']
+    end
+
+    def game_id
+      data['gameId']
+    end
+
+    def publisher
+      data['publisher']
+    end
+
+    def game
+      data['game']
+    end
+
+    def schema
+      @schema ||= DatasetSchema.new(data['schema']) if data['schema']
+    end
+
+    def created_at
+      parse_time(data['createdAt'])
+    end
+
+    def updated_at
+      parse_time(data['updatedAt'])
+    end
+
+    # Schema-aware helpers
+
+    # Get all field keys from the schema.
+    #
+    # @return [Array<String>] List of field keys
+    def field_keys
+      schema&.fields&.map(&:key) || []
+    end
+
+    # Get all filterable field keys.
+    #
+    # @return [Array<String>] List of filterable field keys
+    def filterable_fields
+      schema&.filterable_fields || []
+    end
+
+    # Get all searchable field keys.
+    #
+    # @return [Array<String>] List of searchable field keys
+    def searchable_fields
+      schema&.searchable_fields || []
+    end
+
+    # Get the identifier field key.
+    #
+    # @return [String, nil] The identifier field key or nil if none
+    def identifier_field
+      schema&.fields&.find(&:identifier?)&.key
+    end
+
+    # Check if a field is filterable.
+    #
+    # @param field_key [String, Symbol] The field key
+    # @return [Boolean]
+    def filterable?(field_key)
+      filterable_fields.include?(field_key.to_s)
+    end
+
+    # Check if a field is searchable.
+    #
+    # @param field_key [String, Symbol] The field key
+    # @return [Boolean]
+    def searchable?(field_key)
+      searchable_fields.include?(field_key.to_s)
+    end
+
+    # Get a field's info by key.
+    #
+    # @param field_key [String, Symbol] The field key
+    # @return [FieldInfo, nil] The field info or nil if not found
+    def field(field_key)
+      schema&.field(field_key)
+    end
+
+    # Search records in this dataset.
+    # Unlike datasets on Game, this is NOT cached since filters can vary.
+    #
+    # @param first [Integer, nil] Maximum number of results
+    # @param filter [Hash, nil] Filter conditions (alternative to block)
+    # @yield [FilterBuilder] Optional block for filter DSL
+    # @return [Collection<Record>] Collection of records
+    # @raise [CardDB::Error] If no client is available
+    def records(first: nil, filter: nil, &block)
+      raise Error, 'No client available to fetch records' unless client
+
+      publisher_slug = publisher&.[]('slug')
+      game_key = game&.[]('key')
+
+      raise Error, 'Publisher slug not available on this dataset' unless publisher_slug
+      raise Error, 'Game key not available on this dataset' unless game_key
+
+      client.records.search(
+        publisher_slug: publisher_slug,
+        game_key: game_key,
+        dataset_key: key,
+        first: first,
+        filter: filter,
+        &block
+      )
+    end
+
+    private
+
+    def parse_time(value)
+      return nil unless value
+
+      Time.parse(value)
+    rescue ArgumentError
+      value
+    end
+  end
+
+  # Wrapper for DatasetSchema
+  class DatasetSchema
+    attr_reader :data
+
+    def initialize(data)
+      @data = data || {}
+    end
+
+    def fields
+      @fields ||= (data['fields'] || []).map { |f| FieldInfo.new(f) }
+    end
+
+    def filterable_fields
+      data['filterableFields'] || []
+    end
+
+    def searchable_fields
+      data['searchableFields'] || []
+    end
+
+    def link_fields
+      @link_fields ||= (data['linkFields'] || []).map { |f| LinkFieldInfo.new(f) }
+    end
+
+    # Find a field by key
+    def field(key)
+      fields.find { |f| f.key == key.to_s }
+    end
+  end
+
+  # Wrapper for FieldInfo
+  class FieldInfo
+    attr_reader :data
+
+    def initialize(data)
+      @data = data || {}
+    end
+
+    def key
+      data['key']
+    end
+
+    def label
+      data['label']
+    end
+
+    def description
+      data['description']
+    end
+
+    def type
+      data['type']
+    end
+
+    def required?
+      data['isRequired']
+    end
+
+    def filterable?
+      data['filterable']
+    end
+
+    def searchable?
+      data['searchable']
+    end
+
+    def identifier?
+      data['isIdentifier']
+    end
+
+    def item_type
+      data['itemType']
+    end
+
+    def display_format
+      data['displayFormat']
+    end
+
+    def semantic_type
+      data['semanticType']
+    end
+
+    def allowed_values
+      data['allowedValues']
+    end
+
+    def nested_fields
+      @nested_fields ||= (data['nestedFields'] || []).map { |f| FieldInfo.new(f) }
+    end
+  end
+
+  # Wrapper for LinkFieldInfo
+  class LinkFieldInfo
+    attr_reader :data
+
+    def initialize(data)
+      @data = data || {}
+    end
+
+    def key
+      data['key']
+    end
+
+    def label
+      data['label']
+    end
+
+    def target_dataset_key
+      data['targetDatasetKey']
+    end
+
+    def target_dataset_name
+      data['targetDatasetName']
+    end
+
+    def target_dataset_id
+      data['targetDatasetId']
+    end
+  end
+
+  # Wrapper for DatasetRecord objects
+  class Record < Resource
+    def id
+      data['id']
+    end
+
+    def dataset_id
+      data['datasetId']
+    end
+
+    def record_data
+      data['data']
+    end
+    alias fields record_data
+
+    def dataset
+      data['dataset']
+    end
+
+    def resolved_links
+      @resolved_links ||= parse_resolved_links
+    end
+
+    def created_at
+      parse_time(data['createdAt'])
+    end
+
+    def updated_at
+      parse_time(data['updatedAt'])
+    end
+
+    # Access record data fields directly via bracket notation
+    #
+    # @param key [String, Symbol] The field name
+    # @return [Object, nil] The field value
+    def [](key)
+      record_data&.[](key.to_s)
+    end
+
+    # Access record data fields directly via method calls
+    #
+    # @example
+    #   record.name  # equivalent to record['name']
+    #   record.hp    # equivalent to record['hp']
+    def method_missing(method_name, *args, &block)
+      key = method_name.to_s
+
+      # Only handle reader methods (no args, no block, no assignment)
+      return record_data&.[](key) if args.empty? && block.nil? && !key.end_with?('=')
+
+      super
+    end
+
+    # Support respond_to? for dynamic field access
+    def respond_to_missing?(method_name, include_private = false)
+      key = method_name.to_s
+      return true if record_data&.key?(key)
+
+      super
+    end
+
+    private
+
+    def parse_resolved_links
+      return {} unless data['resolvedLinks']
+
+      data['resolvedLinks'].each_with_object({}) do |link, hash|
+        hash[link['field']] = ResolvedLink.new(link, client: client)
+      end
+    end
+
+    def parse_time(value)
+      return nil unless value
+
+      Time.parse(value)
+    rescue ArgumentError
+      value
+    end
+  end
+
+  # Wrapper for hosted Deck objects
+  class Deck < Resource
+    def id
+      data['id']
+    end
+
+    def account_id
+      data['accountId']
+    end
+
+    def api_application_id
+      data['apiApplicationId']
+    end
+
+    def game_id
+      data['gameId']
+    end
+
+    def game
+      @game ||= data['game'] ? Game.new(data['game'], client: client) : nil
+    end
+
+    def title
+      data['title']
+    end
+
+    def description
+      data['description']
+    end
+
+    def format_key
+      data['formatKey']
+    end
+
+    def visibility
+      data['visibility']
+    end
+
+    def external_ref
+      data['externalRef']
+    end
+
+    def source_url
+      data['sourceUrl']
+    end
+
+    def metadata
+      data['metadata'] || {}
+    end
+
+    def entries
+      @entries ||= (data['entries'] || []).map { |entry| DeckEntry.new(entry, client: client) }
+    end
+
+    def created_at
+      parse_time(data['createdAt'])
+    end
+
+    def updated_at
+      parse_time(data['updatedAt'])
+    end
+
+    private
+
+    def parse_time(value)
+      return nil unless value
+
+      Time.parse(value)
+    rescue ArgumentError
+      value
+    end
+  end
+
+  # Wrapper for hosted DeckEntry objects
+  class DeckEntry < Resource
+    def id
+      data['id']
+    end
+
+    def dataset_id
+      data['datasetId']
+    end
+
+    def record_id
+      data['recordId']
+    end
+
+    def identifier
+      data['identifier']
+    end
+
+    def quantity
+      data['quantity']
+    end
+
+    def section
+      data['section']
+    end
+
+    def sort_order
+      data['sortOrder']
+    end
+
+    def annotations
+      data['annotations'] || {}
+    end
+
+    def record
+      @record ||= data['record'] ? Record.new(data['record'], client: client) : nil
+    end
+  end
+
+  # Wrapper for ResolvedLink
+  # Supports both single links and arrays of links
+  class ResolvedLink
+    attr_reader :data, :client
+
+    def initialize(data, client: nil)
+      @data = data || {}
+      @client = client
+    end
+
+    def field
+      data['field']
+    end
+
+    def link_field_key
+      data['linkFieldKey']
+    end
+
+    # Returns all values (always an array)
+    def values
+      data['values'] || []
+    end
+
+    # Returns all resolved records (parallel array to values, nil for unresolved)
+    def records
+      @records ||= (data['records'] || []).map do |rec|
+        rec ? Record.new(rec, client: client) : nil
+      end
+    end
+
+    # Convenience: first value (for single-link fields)
+    def value
+      values.first
+    end
+
+    # Convenience: first record (for single-link fields)
+    def record
+      records.first
+    end
+  end
+end