carddb 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f38ee7d9b3b04bbbc3cfa0c3b4954cb0a65ee7f61f64f87a7bc07c228cdec60d
+  data.tar.gz: 80759ca9be30df5ef9c3b122caccde5c669d7828d3fbd097d5ad431b2c2885b3
+SHA512:
+  metadata.gz: 8d1f7de2a44deaa670f63f3de0879edb50b271e154d31d788464f457537a91c99e56a8db7a1717ff047456eee7f1f02d1745305f92e3fa9488945386941af6c6
+  data.tar.gz: db96a54832d649c3bb683a01ec1c19a287062ba4ec82b08c201c628e15b407a788d587562f124447d943652d299ccd1b4b8287fd8bedd70e2c2675257022c2ef

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rspec_status

@@ -0,0 +1,96 @@
+example_id                                        | status | run_time        |
+------------------------------------------------- | ------ | --------------- |
+./spec/carddb/client_spec.rb[1:1:1]               | passed | 0.00029 seconds |
+./spec/carddb/client_spec.rb[1:1:2]               | passed | 0.00004 seconds |
+./spec/carddb/client_spec.rb[1:1:3]               | passed | 0.00003 seconds |
+./spec/carddb/client_spec.rb[1:2:1]               | passed | 0.00016 seconds |
+./spec/carddb/client_spec.rb[1:2:2]               | passed | 0.00019 seconds |
+./spec/carddb/client_spec.rb[1:3:1]               | passed | 0.00003 seconds |
+./spec/carddb/client_spec.rb[1:4:1]               | passed | 0.00003 seconds |
+./spec/carddb/client_spec.rb[1:5:1]               | passed | 0.00004 seconds |
+./spec/carddb/client_spec.rb[1:6:1]               | passed | 0.00003 seconds |
+./spec/carddb/client_spec.rb[1:7:1]               | passed | 0.00032 seconds |
+./spec/carddb/client_spec.rb[1:7:2]               | passed | 0.01201 seconds |
+./spec/carddb/collection_spec.rb[1:1:1]           | passed | 0.00006 seconds |
+./spec/carddb/collection_spec.rb[2:1:1]           | passed | 0.00245 seconds |
+./spec/carddb/collection_spec.rb[2:1:2]           | passed | 0.00015 seconds |
+./spec/carddb/collection_spec.rb[2:1:3]           | passed | 0.0004 seconds  |
+./spec/carddb/collection_spec.rb[2:1:4]           | passed | 0.00038 seconds |
+./spec/carddb/collection_spec.rb[2:1:5]           | passed | 0.00005 seconds |
+./spec/carddb/collection_spec.rb[3:1:1]           | passed | 0.00018 seconds |
+./spec/carddb/collection_spec.rb[3:1:2]           | passed | 0.0003 seconds  |
+./spec/carddb/collection_spec.rb[3:1:3]           | passed | 0.00015 seconds |
+./spec/carddb/collection_spec.rb[3:1:4]           | passed | 0.00004 seconds |
+./spec/carddb/configuration_spec.rb[1:1:1]        | passed | 0.00004 seconds |
+./spec/carddb/configuration_spec.rb[1:1:2]        | passed | 0.0001 seconds  |
+./spec/carddb/configuration_spec.rb[1:1:3]        | passed | 0.00004 seconds |
+./spec/carddb/configuration_spec.rb[1:1:4]        | passed | 0.00003 seconds |
+./spec/carddb/configuration_spec.rb[1:1:5]        | passed | 0.00003 seconds |
+./spec/carddb/configuration_spec.rb[1:1:6]        | passed | 0.00003 seconds |
+./spec/carddb/configuration_spec.rb[1:2:1:1]      | passed | 0.00004 seconds |
+./spec/carddb/configuration_spec.rb[1:2:2:1]      | passed | 0.00003 seconds |
+./spec/carddb/configuration_spec.rb[1:2:2:2]      | passed | 0.0001 seconds  |
+./spec/carddb/configuration_spec.rb[1:3:1:1]      | passed | 0.00003 seconds |
+./spec/carddb/configuration_spec.rb[1:3:2:1]      | passed | 0.00003 seconds |
+./spec/carddb/configuration_spec.rb[1:3:2:2]      | passed | 0.00003 seconds |
+./spec/carddb/configuration_spec.rb[1:3:2:3]      | passed | 0.00002 seconds |
+./spec/carddb/configuration_spec.rb[1:4:1]        | passed | 0.00004 seconds |
+./spec/carddb/configuration_spec.rb[1:4:2]        | passed | 0.00003 seconds |
+./spec/carddb/configuration_spec.rb[1:5:1]        | passed | 0.00003 seconds |
+./spec/carddb/filter_builder_spec.rb[1:1:1]       | passed | 0.00004 seconds |
+./spec/carddb/filter_builder_spec.rb[1:1:2]       | passed | 0.00003 seconds |
+./spec/carddb/filter_builder_spec.rb[1:1:3]       | passed | 0.00003 seconds |
+./spec/carddb/filter_builder_spec.rb[1:1:4]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:1:5]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:1:6]       | passed | 0.00003 seconds |
+./spec/carddb/filter_builder_spec.rb[1:1:7]       | passed | 0.00003 seconds |
+./spec/carddb/filter_builder_spec.rb[1:1:8]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:1]       | passed | 0.00003 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:2]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:3]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:4]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:5]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:6]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:7]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:8]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:9]       | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:10]      | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:11]      | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:12]      | passed | 0.00002 seconds |
+./spec/carddb/filter_builder_spec.rb[1:2:13]      | passed | 0.00003 seconds |
+./spec/carddb/resources/datasets_spec.rb[1:1:1]   | passed | 0.00387 seconds |
+./spec/carddb/resources/datasets_spec.rb[1:1:2]   | passed | 0.00363 seconds |
+./spec/carddb/resources/datasets_spec.rb[1:2:1]   | passed | 0.00444 seconds |
+./spec/carddb/resources/decks_spec.rb[1:1:1]      | passed | 0.00427 seconds |
+./spec/carddb/resources/decks_spec.rb[1:2:1]      | passed | 0.00438 seconds |
+./spec/carddb/resources/decks_spec.rb[1:3:1]      | passed | 0.00442 seconds |
+./spec/carddb/resources/decks_spec.rb[1:4:1]      | passed | 0.0043 seconds  |
+./spec/carddb/resources/decks_spec.rb[1:5:1]      | passed | 0.00403 seconds |
+./spec/carddb/resources/decks_spec.rb[1:6:1]      | passed | 0.00384 seconds |
+./spec/carddb/resources/decks_spec.rb[1:7:1]      | passed | 0.00416 seconds |
+./spec/carddb/resources/games_spec.rb[1:1:1]      | passed | 0.00463 seconds |
+./spec/carddb/resources/games_spec.rb[1:1:2]      | passed | 0.00008 seconds |
+./spec/carddb/resources/games_spec.rb[1:2:1]      | passed | 0.00426 seconds |
+./spec/carddb/resources/games_spec.rb[1:2:2]      | passed | 0.00444 seconds |
+./spec/carddb/resources/publishers_spec.rb[1:1:1] | passed | 0.00383 seconds |
+./spec/carddb/resources/publishers_spec.rb[1:2:1] | passed | 0.00447 seconds |
+./spec/carddb/resources/records_spec.rb[1:1:1]    | passed | 0.00428 seconds |
+./spec/carddb/resources/records_spec.rb[1:1:2]    | passed | 0.00416 seconds |
+./spec/carddb/resources/records_spec.rb[1:1:3]    | passed | 0.00012 seconds |
+./spec/carddb/resources/records_spec.rb[1:1:4]    | passed | 0.00004 seconds |
+./spec/carddb/resources/records_spec.rb[1:2:1]    | passed | 0.00412 seconds |
+./spec/carddb/resources/records_spec.rb[1:2:2]    | passed | 0.00414 seconds |
+./spec/carddb/resources/records_spec.rb[1:3:1]    | passed | 0.00444 seconds |
+./spec/carddb/resources/records_spec.rb[1:3:2]    | passed | 0.00011 seconds |
+./spec/carddb/resources/records_spec.rb[1:4:1]    | passed | 0.00365 seconds |
+./spec/carddb/resources/records_spec.rb[1:4:2]    | passed | 0.00004 seconds |
+./spec/carddb/resources/records_spec.rb[1:4:3]    | passed | 0.00009 seconds |
+./spec/carddb/resources/rules_spec.rb[1:1:1]      | passed | 0.00403 seconds |
+./spec/carddb/resources/rules_spec.rb[1:2:1]      | passed | 0.00419 seconds |
+./spec/carddb_spec.rb[1:1]                        | passed | 0.00004 seconds |
+./spec/carddb_spec.rb[1:2:1]                      | passed | 0.00003 seconds |
+./spec/carddb_spec.rb[1:3:1]                      | passed | 0.00003 seconds |
+./spec/carddb_spec.rb[1:4:1]                      | passed | 0.00004 seconds |
+./spec/carddb_spec.rb[1:5:1]                      | passed | 0.00003 seconds |
+./spec/carddb_spec.rb[1:6:1]                      | passed | 0.00003 seconds |
+./spec/carddb_spec.rb[1:7:1]                      | passed | 0.00003 seconds |

data/.rubocop.yml

@@ -0,0 +1,72 @@
+plugins:
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    - "vendor/**/*"
+    - "spec/fixtures/**/*"
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+Metrics/MethodLength:
+  Max: 35
+
+Metrics/AbcSize:
+  Max: 40
+
+Metrics/ClassLength:
+  Max: 450
+
+Metrics/ModuleLength:
+  Max: 450
+
+Metrics/ParameterLists:
+  Max: 10
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Layout/LineLength:
+  Max: 250
+
+Naming/MethodParameterName:
+  MinNameLength: 2
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Style/ComparableClamp:
+  Enabled: false
+
+Style/SafeNavigationChainLength:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 40
+
+RSpec/MultipleExpectations:
+  Max: 5
+
+RSpec/NestedGroups:
+  Max: 4
+
+RSpec/SpecFilePathFormat:
+  Enabled: false
+
+RSpec/MultipleDescribes:
+  Enabled: false
+
+RSpec/IdenticalEqualityAssertion:
+  Enabled: false

data/AGENTS.md

@@ -0,0 +1,27 @@
+# AGENTS.md
+
+## Commands
+- `bundle exec rspec` - run all tests
+- `bundle exec rspec spec/carddb/client_spec.rb` - run single test file
+- `bundle exec rspec spec/carddb/client_spec.rb:42` - run test at line
+- `bundle exec rubocop` - run linter
+- `bundle exec rake` - run tests + linter (default)
+
+## Code Style
+- Add `# frozen_string_literal: true` at top of all files
+- Use `require_relative` for internal requires, not `require`
+- Prefer single-quoted strings unless interpolation needed
+- Module name is `CardDB` (capital D and B)
+- Classes: PascalCase, methods/variables: snake_case, constants: SCREAMING_SNAKE_CASE
+- Use keyword arguments for optional parameters
+- Document public methods with YARD (`@param`, `@return`, `@raise`)
+
+## Error Handling
+- Raise `ArgumentError` for invalid arguments
+- Use custom errors from `CardDB::Error` hierarchy for API issues
+
+## Testing
+- Use `described_class` instead of repeating class name
+- Use `let` for test data, `subject(:name)` for named subjects
+- Stub API calls with `stub_graphql_response(data)` helper
+- Group tests by method: `describe "#method_name"`

data/CHANGELOG.md

@@ -0,0 +1,127 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-04-29
+
+### Added
+
+- **Publishers Resource**: New `CardDB.publishers` resource for searching and fetching publishers
+  - `search(search:, first:, after:)` - Search publishers by name
+  - `fetch(id:)` or `fetch(slug:)` - Fetch a single publisher by ID or slug
+  - `fetch_many(slugs)` - Fetch multiple publishers by slugs
+  - `Publisher#games` - Navigate from publisher to games
+
+- **Records.get Method**: Fetch records by identifier value using the dataset's identifier field
+  ```ruby
+  record = CardDB.records.get(
+    identifier: "xy1-1",
+    dataset_key: "cards"
+  )
+  ```
+
+- **Batch Query Support**: Combine multiple queries into a single API request
+  ```ruby
+  results = CardDB.batch do |b|
+    b.games.fetch("uuid-1")
+    b.publishers.fetch(slug: "pokemon-company")
+  end
+  ```
+
+- **Configurable Logging**: Debug API interactions with configurable logging
+  ```ruby
+  CardDB.configure do |config|
+    config.logger = Logger.new(STDOUT)
+    config.log_level = :debug  # :debug, :info, :warn, :error
+  end
+  ```
+
+- **Auto-Retry on Rate Limit**: Automatically retry requests when rate limited
+  ```ruby
+  CardDB.configure do |config|
+    config.retry_on_rate_limit = true
+    config.max_retries = 3
+  end
+  ```
+
+- **Configurable Caching**: Cache fetch/get results to reduce API calls
+  ```ruby
+  CardDB.configure do |config|
+    config.cache = CardDB::MemoryCache.new  # or Rails.cache
+    config.cache_ttl = 300  # Default: 5 minutes
+    
+    # Per-resource TTLs (override the default)
+    config.cache_ttls = {
+      publishers: 3600,   # 1 hour
+      games: 3600,        # 1 hour
+      datasets: 1800,     # 30 minutes
+      records: 300        # 5 minutes
+    }
+  end
+  
+  # Per-request control
+  game = CardDB.games.fetch("uuid", cache: true)
+  game = CardDB.games.fetch("uuid", cache: false)
+  ```
+
+- **Batch Iteration Methods**: Rails-style `find_each` and `find_in_batches` on Collection
+  ```ruby
+  collection.find_each { |record| process(record) }
+  collection.find_in_batches(batch_size: 50) { |batch| ... }
+  ```
+
+- **Schema-Aware Dataset Helpers**: Convenient methods for working with dataset schemas
+  - `dataset.field_keys` - All field keys
+  - `dataset.filterable_fields` - Filterable field keys
+  - `dataset.searchable_fields` - Searchable field keys
+  - `dataset.identifier_field` - The identifier field key
+  - `dataset.filterable?(:field)` - Check if field is filterable
+  - `dataset.searchable?(:field)` - Check if field is searchable
+  - `dataset.field(:key)` - Get field info by key
+
+- **Dynamic Field Access on Record**: Access record data via method calls
+  ```ruby
+  record.name   # equivalent to record['name']
+  record.hp     # equivalent to record['hp']
+  ```
+
+- **MemoryCache**: Thread-safe in-memory cache with TTL support
+  ```ruby
+  cache = CardDB::MemoryCache.new
+  cache.write("key", "value", expires_in: 60)
+  cache.read("key")  # => "value"
+  ```
+
+### Changed
+
+- **Games.get Method**: Now uses unified `fetchGame` query with optional parameters
+- **Datasets.get Method**: Now uses unified `fetchDataset` query with optional parameters
+
+### Fixed
+
+- Fixed duplicate return statement in `Batch#build_publisher_query`
+
+## [0.1.0] - 2024-12-16
+
+### Added
+
+- Initial release
+- Client configuration (API key, endpoint, timeouts, defaults, restrictions)
+- Games resource (search, fetch)
+- Datasets resource (search, fetch, get, schema)
+- Records resource (search, fetch, fetch_many)
+- Expressive filter DSL with operators (eq, neq, gt, gte, lt, lte, within, not_within, contains, like, ilike, is_null, is_not_null)
+- Boolean logic in filters (AND, OR via `any` blocks)
+- Nested field filtering
+- Link filtering (`where_link`)
+- Link resolution in search results
+- Pagination support (manual, auto_paginate)
+- Collection class with Enumerable support
+- Resource wrapper classes (Game, Dataset, Record, DatasetSchema, FieldInfo)
+- Comprehensive error handling (AuthenticationError, RateLimitError, RestrictedError, NotFoundError, ValidationError, GraphQLError, ConnectionError, TimeoutError)
+- Rate limit info access

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 CardDB Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.