carddb-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d0b3bef990ba77cc06d5bcefe584ce475e8a86a9c760850f85b927477cf2b793
+  data.tar.gz: bf78dc4b0c53c3e800ed79a229fdda92ae5e4fa26225674a13919fed7333f3da
+SHA512:
+  metadata.gz: 42c1c12ae51af8f11c2d0ed65c0f7972b50bd6ae5980aa17dd4aaae28b36f61e250d6ebd3b5156b6785085cc9364b4c0e322f11996b16247c7fb24cf67ad9a06
+  data.tar.gz: 377b72303e57d2621bacfa851977be257e6104a3acb2134109f12de04fb33ba58f184f7a05ec024336534e0e59a9a0cbee8e504836268771d3b6ffac73919082

data/CHANGELOG.md

@@ -0,0 +1,24 @@
+# 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]
+
+### Added
+
+- Rails integration for the `carddb` gem via `Railtie`, install generator, and controller helpers.
+- Active Record model helpers for CardDB records, decks, games, datasets, publishers, and game-scoped dataset collections.
+- `GraphQL::Batch` loaders and `GraphQL::Dataloader` sources for CardDB records, decks, games, datasets, and publishers.
+- GraphQL field macros for CardDB-backed resources and dataset list relationships.
+- Explicit deck sync, import, and export service wrappers plus `ActiveJob` support for deck sync jobs.
+- Token-aware deck controller helpers for preview, embed, access, and access-token exchange flows.
+- CI, publish helper script, and gem release metadata aligned with the `carddb` Ruby client.
+
+## [0.1.0] - 2026-06-17
+
+### Added
+
+- Initial public release of `carddb-rails`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 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.

data/README.md

@@ -0,0 +1,494 @@
+# CardDB Rails
+
+Rails integration for the [`carddb`](https://github.com/xtda/carddb-ruby) gem.
+
+This gem keeps the base CardDB client framework-agnostic and adds Rails-specific conveniences:
+
+- initializer and Railtie wiring
+- `carddb_client` controller helper
+- explicit Active Record model helpers
+- `GraphQL::Batch` loaders for CardDB records, games, datasets, and publishers
+- `GraphQL::Dataloader` sources for the same resource lookups
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'carddb'
+gem 'carddb-rails'
+```
+
+Then run:
+
+```bash
+bundle install
+bin/rails generate carddb:install
+```
+
+## Configuration
+
+The generated initializer configures CardDB from `Rails.application.credentials[:carddb]` and wires `Rails.cache` and `Rails.logger` by default.
+
+Expected credentials shape:
+
+```ruby
+carddb:
+  publishable_key: carddb_pk_xxx
+  secret_key: carddb_sk_xxx
+  access_token: carddb_oat_xxx
+  api_key: carddb_legacy_xxx
+  endpoint: https://carddb.xtda.org/query
+```
+
+## Controller Helper
+
+Controllers get a `carddb_client` helper:
+
+```ruby
+class CardsController < ApplicationController
+  def show
+    @card = carddb_client.records.get(
+      publisher_slug: 'pokemon-company',
+      game_key: 'pokemon-tcg',
+      dataset_key: 'cards',
+      identifier: params[:id]
+    )
+  end
+end
+```
+
+## Model Helper
+
+Include `CardDB::Rails::HasCardDBRecord` in models that hold a CardDB identifier locally.
+
+```ruby
+class DeckEntry < ApplicationRecord
+  include CardDB::Rails::HasCardDBRecord
+
+  has_carddb_record \
+    dataset_key: 'cards',
+    publisher_slug: 'pokemon-company',
+    game_key: 'pokemon-tcg',
+    identifier: :card_identifier
+end
+```
+
+This defines:
+
+- `carddb_record`
+- `carddb_record!`
+- `reload_carddb_record`
+- `carddb_record_loaded?`
+
+Additional helpers are available for other CardDB resources:
+
+```ruby
+class DeckTemplate < ApplicationRecord
+  include CardDB::Rails::HasCardDBGame
+  include CardDB::Rails::HasCardDBDataset
+
+  has_carddb_game game_key: :game_key, publisher_slug: 'pokemon-company'
+  has_carddb_dataset dataset_key: :dataset_key, publisher_slug: 'pokemon-company', game_key: :game_key
+end
+```
+
+For deck-backed models, use `HasCardDBDeck`:
+
+```ruby
+class TournamentDeck < ApplicationRecord
+  include CardDB::Rails::HasCardDBDeck
+
+  has_carddb_deck id: :carddb_deck_id
+end
+```
+
+Or map a local record to an app-owned CardDB deck by external reference:
+
+```ruby
+class TournamentDeck < ApplicationRecord
+  include CardDB::Rails::HasCardDBDeck
+
+  has_carddb_deck external_ref: :external_ref
+end
+```
+
+That gives you:
+
+- `carddb_deck`
+- `carddb_deck!`
+- `reload_carddb_deck`
+- `carddb_deck_loaded?`
+
+To batch-preload deck helpers for many records:
+
+```ruby
+TournamentDeck.preload_carddb_decks(records)
+```
+
+If a model should expose the available datasets for its game, use `HasCardDBDatasets`:
+
+```ruby
+class DeckTemplate < ApplicationRecord
+  include CardDB::Rails::HasCardDBGame
+  include CardDB::Rails::HasCardDBDatasets
+
+  has_carddb_game game_key: :game_key, publisher_slug: 'pokemon-company'
+  has_carddb_datasets publisher_slug: 'pokemon-company', game_key: :game_key
+end
+```
+
+That gives you:
+
+- `carddb_datasets`
+- `reload_carddb_datasets`
+- `carddb_datasets_loaded?`
+- `carddb_dataset('cards')`
+
+Example:
+
+```ruby
+template.carddb_datasets
+template.carddb_dataset('cards')
+template.carddb_datasets(purpose: 'RULES', search: 'rotation')
+```
+
+You can also use dynamic values:
+
+```ruby
+class CollectionItem < ApplicationRecord
+  include CardDB::Rails::HasCardDBRecord
+
+  has_carddb_record \
+    dataset_key: :carddb_dataset_key,
+    publisher_slug: :carddb_publisher_slug,
+    game_key: :carddb_game_key,
+    identifier: :carddb_identifier
+end
+```
+
+Or define multiple named mappings:
+
+```ruby
+class MatchResult < ApplicationRecord
+  include CardDB::Rails::HasCardDBRecord
+
+  has_carddb_record :home_card,
+    dataset_key: 'cards',
+    publisher_slug: 'pokemon-company',
+    game_key: 'pokemon-tcg',
+    identifier: :home_card_identifier
+
+  has_carddb_record :away_card,
+    dataset_key: 'cards',
+    publisher_slug: 'pokemon-company',
+    game_key: 'pokemon-tcg',
+    identifier: :away_card_identifier
+end
+```
+
+To batch-preload a CardDB helper for many records:
+
+```ruby
+DeckEntry.preload_carddb_records(entries)
+```
+
+This uses CardDB's batch API and memoizes the loaded records back onto each model instance.
+
+## GraphQL::Batch Loader
+
+This gem includes a `GraphQL::Batch` loader that fetches CardDB records in one remote batch request:
+
+```ruby
+class Types::DeckEntry < Types::BaseObject
+  field :carddb_record, Types::CarddbRecord, null: true
+
+  def carddb_record
+    CardDB::Rails::GraphQL::RecordLoader.for(
+      dataset_key: 'cards',
+      publisher_slug: 'pokemon-company',
+      game_key: 'pokemon-tcg'
+    ).load(object.card_identifier)
+  end
+end
+```
+
+If your Rails app already uses `GraphQL::Batch`, this prevents one CardDB HTTP request per node.
+
+Available loaders:
+
+- `CardDB::Rails::GraphQL::DeckLoader`
+- `CardDB::Rails::GraphQL::DeckByExternalRefLoader`
+- `CardDB::Rails::GraphQL::RecordLoader`
+- `CardDB::Rails::GraphQL::GameLoader`
+- `CardDB::Rails::GraphQL::DatasetLoader`
+- `CardDB::Rails::GraphQL::PublisherLoader`
+
+If your schema uses `GraphQL::Dataloader` instead of `GraphQL::Batch`, parallel sources are also available:
+
+- `CardDB::Rails::GraphQL::Dataloader::RecordSource`
+- `CardDB::Rails::GraphQL::Dataloader::DeckSource`
+- `CardDB::Rails::GraphQL::Dataloader::DeckByExternalRefSource`
+- `CardDB::Rails::GraphQL::Dataloader::GameSource`
+- `CardDB::Rails::GraphQL::Dataloader::DatasetSource`
+- `CardDB::Rails::GraphQL::Dataloader::PublisherSource`
+
+Example:
+
+```ruby
+class Types::DeckEntry < Types::BaseObject
+  field :carddb_record, Types::CarddbRecord, null: true
+
+  def carddb_record
+    dataloader.with(
+      CardDB::Rails::GraphQL::Dataloader::RecordSource,
+      dataset_key: 'cards',
+      publisher_slug: 'pokemon-company',
+      game_key: object.game_key
+    ).load(object.card_identifier)
+  end
+end
+```
+
+You can also use dataloader-backed field macros directly:
+
+```ruby
+class Types::DeckEntry < Types::BaseObject
+  carddb_record_dataloader_field :carddb_record,
+    type: Types::CarddbRecord,
+    identifier: :card_identifier,
+    dataset_key: 'cards',
+    publisher_slug: 'pokemon-company',
+    game_key: :game_key
+end
+```
+
+Deck fields are also available in both styles:
+
+```ruby
+class Types::TournamentDeck < Types::BaseObject
+  carddb_deck_field :carddb_deck,
+    type: Types::CarddbDeck,
+    id: :carddb_deck_id
+
+  carddb_deck_dataloader_field :carddb_deck_async,
+    type: Types::CarddbDeck,
+    id: :carddb_deck_id
+end
+```
+
+External-ref lookups use the same macros:
+
+```ruby
+class Types::TournamentDeck < Types::BaseObject
+  carddb_deck_field :carddb_deck,
+    type: Types::CarddbDeck,
+    external_ref: :external_ref
+
+  carddb_deck_dataloader_field :carddb_deck_async,
+    type: Types::CarddbDeck,
+    external_ref: :external_ref
+end
+```
+
+## Deck Sync Helpers
+
+For write flows, keep sync explicit with the provided service and job:
+
+```ruby
+CardDB::Rails::DeckSyncService.call(
+  external_ref: 'deck-ext-1',
+  input: {
+    title: 'Pikachu League Cup',
+    visibility: 'PRIVATE'
+  }
+)
+```
+
+```ruby
+CardDB::Rails::DeckSyncJob.perform_later(
+  external_ref: 'deck-ext-1',
+  input: {
+    title: 'Pikachu League Cup',
+    visibility: 'PRIVATE'
+  }
+)
+```
+
+These helpers call `client.decks.upsert_by_external_ref(...)` and do not hide writes behind model callbacks.
+
+## Deck Import / Export Helpers
+
+For explicit service-style import and export flows:
+
+```ruby
+CardDB::Rails::DeckImportService.call(
+  input: {
+    deckId: 'deck_123',
+    text: "4 Pikachu\n4 Rare Candy",
+    format: 'SIMPLE_TEXT'
+  }
+)
+```
+
+```ruby
+CardDB::Rails::DeckExportService.call(
+  deck_id: 'deck_123',
+  format: 'JSON'
+)
+```
+
+## Deck Token Controller Helpers
+
+Controllers automatically get token-aware helpers for deck preview/embed/access flows:
+
+```ruby
+class DeckPreviewsController < ApplicationController
+  def show
+    @deck = carddb_preview_deck(params[:token])
+  end
+end
+```
+
+Available helpers:
+
+- `carddb_preview_deck(token)`
+- `carddb_embed_deck(token)`
+- `carddb_access_deck(token)`
+- `carddb_exchange_deck_access_token(input)`
+
+## GraphQL Field Helper
+
+If you want a thin schema macro on top of the loader, extend `CardDB::Rails::GraphQL::Helpers` in your base object:
+
+```ruby
+class Types::BaseObject < GraphQL::Schema::Object
+  extend CardDB::Rails::GraphQL::Helpers
+end
+```
+
+Then define CardDB-backed fields declaratively:
+
+```ruby
+class Types::DeckEntry < Types::BaseObject
+  carddb_record_field :carddb_record,
+    type: Types::CarddbRecord,
+    identifier: :card_identifier,
+    dataset_key: 'cards',
+    publisher_slug: 'pokemon-company',
+    game_key: 'pokemon-tcg'
+end
+```
+
+For a list relationship, use `carddb_datasets_field`:
+
+```ruby
+class Types::DeckTemplate < Types::BaseObject
+  carddb_datasets_field :carddb_datasets,
+    type: [Types::CarddbDataset],
+    publisher_slug: 'pokemon-company',
+    game_key: :game_key
+end
+```
+
+If the underlying model includes `HasCardDBDatasets`, this field uses the model helper directly.
+
+If you prefer dataloader-oriented naming consistency, `carddb_datasets_dataloader_field` is also available.
+
+## Integration Coverage
+
+The gem includes coverage for:
+
+- Railtie configuration wiring via `CardDB::Rails.apply_rails_configuration!`
+- install generator output for `config/initializers/carddb.rb`
+
+You can also expose related CardDB resources directly:
+
+```ruby
+class Types::DeckTemplate < Types::BaseObject
+  carddb_game_field :carddb_game,
+    type: Types::CarddbGame,
+    game_key: :game_key,
+    publisher_slug: 'pokemon-company'
+
+  carddb_dataset_field :carddb_dataset,
+    type: Types::CarddbDataset,
+    dataset_key: :dataset_key,
+    publisher_slug: 'pokemon-company',
+    game_key: :game_key
+
+  carddb_publisher_field :carddb_publisher,
+    type: Types::CarddbPublisher,
+    slug: :publisher_slug
+end
+```
+
+## Rails + GraphQL Example
+
+For a GraphQL app that already uses `GraphQL::Batch`, a good pattern is:
+
+```ruby
+class DeckEntry < ApplicationRecord
+  include CardDB::Rails::HasCardDBRecord
+  include CardDB::Rails::HasCardDBGame
+
+  has_carddb_record \
+    dataset_key: 'cards',
+    publisher_slug: 'pokemon-company',
+    game_key: :game_key,
+    identifier: :card_identifier
+
+  has_carddb_game \
+    game_key: :game_key,
+    publisher_slug: 'pokemon-company'
+end
+```
+
+```ruby
+class Types::BaseObject < GraphQL::Schema::Object
+  extend CardDB::Rails::GraphQL::Helpers
+end
+```
+
+```ruby
+class Types::DeckEntry < Types::BaseObject
+  field :id, ID, null: false
+
+  carddb_record_field :carddb_record,
+    type: Types::CarddbRecord,
+    identifier: :card_identifier,
+    dataset_key: 'cards',
+    publisher_slug: 'pokemon-company',
+    game_key: :game_key
+
+  carddb_game_field :carddb_game,
+    type: Types::CarddbGame,
+    game_key: :game_key,
+    publisher_slug: 'pokemon-company'
+end
+```
+
+That keeps the Active Record model explicit while letting GraphQL batch remote CardDB lookups across sibling nodes.
+
+If you want to expose all datasets for a game in GraphQL, a good pattern is to call the model helper directly:
+
+```ruby
+class Types::DeckTemplate < Types::BaseObject
+  field :carddb_datasets, [Types::CarddbDataset], null: false
+
+  def carddb_datasets
+    object.carddb_datasets
+  end
+end
+```
+
+## Boundaries
+
+This gem intentionally does not:
+
+- make CardDB objects behave like `ActiveRecord::Relation`
+- define remote CardDB fields directly on your models
+- perform implicit remote lookups in callbacks or validations
+- sync CardDB data into local tables
+
+The intent is explicit remote access with Rails-friendly ergonomics.

data/lib/carddb/rails/configuration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Rails
+    class Configuration
+      attr_accessor :client, :credentials_key, :use_rails_cache, :use_rails_logger
+
+      def initialize
+        @client = nil
+        @credentials_key = :carddb
+        @use_rails_cache = true
+        @use_rails_logger = true
+      end
+    end
+  end
+end

data/lib/carddb/rails/controller_helpers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Rails
+    module ControllerHelpers
+      def carddb_client
+        CardDB::Rails.client
+      end
+    end
+  end
+end

data/lib/carddb/rails/deck_controller_helpers.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Rails
+    module DeckControllerHelpers
+      def carddb_preview_deck(token, client: carddb_client)
+        client.decks.preview(token: token)
+      end
+
+      def carddb_embed_deck(token, client: carddb_client)
+        client.decks.embed(token: token)
+      end
+
+      def carddb_access_deck(token, client: carddb_client)
+        client.decks.access(token: token)
+      end
+
+      def carddb_exchange_deck_access_token(input, client: carddb_client)
+        client.decks.exchange_access_token(input: input)
+      end
+
+      def carddb_exchange_deck_session_token(input, client: carddb_client)
+        client.decks.exchange_session_token(input: input)
+      end
+    end
+  end
+end

data/lib/carddb/rails/deck_export_service.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Rails
+    class DeckExportService
+      def self.call(deck_id:, format: 'SIMPLE_TEXT', client: nil)
+        new(deck_id: deck_id, format: format, client: client).call
+      end
+
+      def initialize(deck_id:, format: 'SIMPLE_TEXT', client: nil)
+        @deck_id = deck_id
+        @format = format
+        @client = client || CardDB::Rails.client
+      end
+
+      def call
+        @client.decks.export_deck(id: @deck_id, format: @format)
+      end
+    end
+  end
+end

data/lib/carddb/rails/deck_import_service.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Rails
+    class DeckImportService
+      def self.call(input:, client: nil)
+        new(input: input, client: client).call
+      end
+
+      def initialize(input:, client: nil)
+        @input = input
+        @client = client || CardDB::Rails.client
+      end
+
+      def call
+        @client.decks.import_deck(input: @input)
+      end
+    end
+  end
+end

data/lib/carddb/rails/deck_sync_job.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'active_job'
+
+module CardDB
+  module Rails
+    class DeckSyncJob < ActiveJob::Base
+      queue_as :default
+
+      def perform(external_ref:, input:)
+        DeckSyncService.call(external_ref: external_ref, input: input)
+      end
+    end
+  end
+end

data/lib/carddb/rails/deck_sync_service.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Rails
+    class DeckSyncService
+      def self.call(external_ref:, input:, client: nil)
+        new(external_ref: external_ref, input: input, client: client).call
+      end
+
+      def initialize(external_ref:, input:, client: nil)
+        @external_ref = external_ref
+        @input = input
+        @client = client || CardDB::Rails.client
+      end
+
+      def call
+        @client.decks.upsert_by_external_ref(input: @input.merge(externalRef: @external_ref))
+      end
+    end
+  end
+end