CardDB Rails

Rails integration for the carddb 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:

gem 'carddb'
gem 'carddb-rails'

Then run:

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:

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:

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.

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:

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:

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:

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:

TournamentDeck.preload_carddb_decks(records)

If a model should expose the available datasets for its game, use HasCardDBDatasets:

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:

template.carddb_datasets
template.carddb_dataset('cards')
template.carddb_datasets(purpose: 'RULES', search: 'rotation')

You can also use dynamic values:

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:

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:

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:

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:

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:

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:

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:

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:

CardDB::Rails::DeckSyncService.call(
  external_ref: 'deck-ext-1',
  input: {
    title: 'Pikachu League Cup',
    visibility: 'PRIVATE'
  }
)

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:

CardDB::Rails::DeckImportService.call(
  input: {
    deckId: 'deck_123',
    text: "4 Pikachu\n4 Rare Candy",
    format: 'SIMPLE_TEXT'
  }
)

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:

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:

class Types::BaseObject < GraphQL::Schema::Object
  extend CardDB::Rails::GraphQL::Helpers
end

Then define CardDB-backed fields declaratively:

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:

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:

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:

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

class Types::BaseObject < GraphQL::Schema::Object
  extend CardDB::Rails::GraphQL::Helpers
end

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:

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.