carddb 0.2.2 → 0.3.5

data/README.md

@@ -50,7 +50,10 @@ records.each { |record| puts record.name }
 ```ruby
 CardDB.configure do |config|
   # Authentication (optional but recommended)
-  config.api_key = "carddb_your_api_key"
+  config.publishable_key = "carddb_pk_public_key"   # Public/read-oriented credential
+  config.secret_key = "carddb_sk_your_secret_key" # Server-side trusted workflows
+  config.access_token = "carddb_oat_user_token"   # OAuth user-authorized requests
+  config.api_key = "carddb_legacy_key"            # Legacy low-level API key
   
   # Endpoint (defaults to production)
   config.endpoint = "https://carddb.xtda.org/query"
@@ -87,7 +90,7 @@ end
 
 ```ruby
 client = CardDB::Client.new(
-  api_key: "carddb_different_key",
+  secret_key: "carddb_sk_different_key",
   default_publisher: "wizards",
   default_game: "magic-the-gathering"
 )
@@ -95,6 +98,13 @@ client = CardDB::Client.new(
 records = client.records.search(dataset_key: "cards")
 ```
 
+Credential guidance:
+
+- Use `publishable_key` for public reads and OAuth setup flows.
+- Use `access_token` for user-authorized deck workflows.
+- Use `secret_key` only in trusted server runtimes for publisher management, app-owned deck sync, and token exchange.
+- Secret-only helpers fail before making a request if `access_token` or `publishable_key` would be sent instead of a secret credential.
+
 ## Usage
 
 ### Publishers
@@ -182,6 +192,184 @@ dataset.searchable?(:name)  # Check if field is searchable
 dataset.field(:hp)          # Get field info by key
 ```
 
+### Publisher Workflows
+
+Publisher-management writes require a trusted server-side `secret_key` or legacy `api_key`.
+They fail before making a request if a `publishable_key` or OAuth `access_token` would be used.
+
+```ruby
+client = CardDB::Client.new(secret_key: ENV.fetch('CARDDB_SECRET_KEY'))
+
+# Games and datasets
+games = client.games.list(publisher_id: 'publisher_uuid')
+game = client.games.get_by_key(publisher_id: 'publisher_uuid', game_key: 'pokemon-tcg')
+game ||= client.games.create(
+  input: {
+    publisherId: 'publisher_uuid',
+    key: 'pokemon-tcg',
+    name: 'Pokemon TCG',
+    visibility: 'PRIVATE'
+  }
+)
+game = client.games.update(id: game.id, input: { description: 'Publisher-managed game' })
+dataset = client.datasets.get_by_key(game_id: game.id, dataset_key: 'cards')
+schema = client.datasets.get_schema(id: dataset.id)
+
+# Import formats
+formats = client.import_formats.list(game_id: game.id)
+client.import_formats.create(
+  input: {
+    gameId: game.id,
+    key: 'pokemon-live',
+    name: 'Pokemon Live',
+    config: { schemaVersion: 1 }
+  }
+)
+
+# Files and imports
+upload = client.files.request_upload(
+  input: {
+    filename: 'cards.json',
+    contentType: 'application/json',
+    size: 12_345,
+    isPublic: false,
+    publisherId: 'publisher_uuid'
+  }
+)
+
+job = client.imports.run(
+  input: {
+    datasetId: dataset.id,
+    fileId: upload.file.id,
+    format: 'JSON',
+    options: { mode: 'STRICT', onConflict: 'UPDATE' }
+  }
+)
+client.imports.wait_for_job(job.id)
+
+# Batch upserts and explicit deletes
+dry_run = client.records.upsert_batch(
+  input: {
+    datasetId: dataset.id,
+    records: [{ identifier: 'CARD-001', name: 'Pikachu' }],
+    options: { dryRun: true }
+  }
+)
+puts dry_run.dry_run_result.errors.map(&:index)
+
+delete_job = client.records.delete_batch(
+  input: { datasetId: dataset.id, identifiers: ['CARD-001'], dryRun: true }
+)
+puts delete_job.results.map(&:status)
+
+# Exports
+export = client.exports.run(input: { datasetId: dataset.id, format: 'JSON' })
+export = client.exports.wait_for_job(export.id)
+puts export.download_url
+```
+
+Publisher import source modes:
+
+- Direct payload: use `records`, `data`, or `imports.run(input: { data: ... })` for small CI payloads and tests.
+- Uploaded file: use `files.request_upload`, PUT bytes to `upload_url`, `files.confirm_upload`, then pass `fileId` for larger JSON/CSV imports.
+- Source URL: pass `sourceUrl` when CardDB should fetch and snapshot an HTTPS source before processing.
+
+Existing-schema imports validate against the current dataset schema and reject unexpected fields:
+
+```ruby
+validation = client.imports.validate(
+  input: {
+    datasetId: dataset.id,
+    records: [{ identifier: 'CARD-001', name: 'Example Card' }],
+    options: { mode: 'STRICT', onConflict: 'UPDATE', dryRun: true }
+  }
+)
+
+validation.errors.each do |error|
+  puts "#{error.dataset_key}[#{error.index}]: #{error.errors.map(&:message).join(', ')}"
+end
+
+job = client.imports.run(
+  input: {
+    datasetId: dataset.id,
+    sourceUrl: 'https://publisher.example/cards.json',
+    format: 'JSON',
+    options: { mode: 'STRICT', onConflict: 'UPDATE' }
+  }
+)
+client.imports.wait_for_job(job.id)
+```
+
+Advanced game imports can create or update datasets and schemas in dependency order:
+
+```ruby
+advanced_data = {
+  datasets: [
+    {
+      name: 'sets',
+      schema: {
+        code: { type: 'STRING', isIdentifier: true },
+        name: { type: 'STRING', required: true }
+      },
+      records: [{ code: 'BASE', name: 'Base Set' }]
+    },
+    {
+      name: 'cards',
+      schema: {
+        identifier: { type: 'STRING', isIdentifier: true },
+        set_id: { type: 'LINK', linkDataset: '$sets', linkFieldKey: 'code' }
+      },
+      records: [{ identifier: 'BASE-001', set_id: 'BASE' }]
+    }
+  ]
+}
+
+preview = client.imports.preview_game(input: { gameId: game.id, data: advanced_data })
+raise preview.warnings.map(&:message).join(', ') unless preview.can_proceed?
+
+game_import = client.imports.run_game(
+  input: {
+    gameId: game.id,
+    data: advanced_data,
+    options: { mode: 'CREATE', onConflict: 'UPDATE' }
+  }
+)
+client.imports.wait_for_game_job(game_import.id)
+```
+
+Schema introspection is useful before building import mappings or generated forms:
+
+```ruby
+schema = client.datasets.get_schema(game_id: game.id, dataset_key: 'cards')
+identifier = schema.fields.find(&:identifier?)&.key
+puts "Identifier field: #{identifier}"
+```
+
+Bulk delete is explicit. Preview first with `dryRun: true`, then execute by sending the same target set with `dryRun: false`.
+
+```ruby
+preview = client.records.delete_batch(
+  input: { datasetId: dataset.id, identifiers: ['CARD-001'], dryRun: true }
+)
+puts preview.results.map { |result| [result.target, result.status] }
+
+delete_job = client.records.delete_batch(
+  input: { datasetId: dataset.id, identifiers: ['CARD-001'], dryRun: false }
+)
+client.records.wait_for_delete_job(delete_job.id)
+```
+
+Exports produce signed download URLs. Refresh a completed job when the URL is stale but the export file still exists.
+
+```ruby
+export_job = client.exports.run(input: { datasetId: dataset.id, format: 'CSV' })
+completed = client.exports.wait_for_job(export_job.id)
+fresh = client.exports.refresh_url(id: completed.id)
+puts fresh.download_url
+```
+
+See [`examples/publisher_content_pipeline.rb`](examples/publisher_content_pipeline.rb) for a CI/CD-style content pipeline example.
+
 ### Rules and Formats
 
 ```ruby
@@ -207,6 +395,210 @@ rules = CardDB.rules.list(
 )
 ```
 
+### Hosted Decks
+
+```ruby
+# OAuth/user-owned or server-owned list and lookup helpers
+decks = CardDB.decks.list_mine(include_archived: false)
+public_decks = CardDB.decks.list_public(filter: { discoverability: "LISTED" })
+deck = CardDB.decks.fetch_mine(decks.first.id)
+
+# Metadata updates are separate from entry mutations
+updated = CardDB.decks.update_metadata(
+  id: deck.id,
+  input: {
+    expectedDraftRevision: deck.draft_revision,
+    title: "Updated title"
+  }
+)
+
+entry_payload = CardDB.decks.add_entry(
+  input: {
+    deckId: updated.id,
+    expectedDraftRevision: updated.draft_revision,
+    datasetKey: "cards",
+    identifier: "CARD-001",
+    quantity: 4
+  }
+)
+
+validation = CardDB.decks.validate(id: updated.id)
+publish = CardDB.decks.publish(
+  id: updated.id,
+  input: { expectedDraftRevision: entry_payload.deck.draft_revision }
+)
+
+puts publish.blockers.map(&:message) unless publish.blockers.empty?
+puts CardDB.decks.export_deck(id: updated.id).text
+
+# Import with publisher-configured format auto-detection
+imported = CardDB.decks.import_deck(
+  input: {
+    deckId: updated.id,
+    text: "1 Iron Leaves ex TEF 25",
+    autoDetect: true,
+    dryRun: true
+  }
+)
+
+puts "Detected #{imported.detection.name} (#{imported.detection.confidence})"
+
+# Or force one configured import format by key/id
+CardDB.decks.import_deck(
+  input: {
+    deckId: updated.id,
+    format: "CONFIGURED",
+    importFormatKey: "pokemon-live",
+    text: "1 Iron Leaves ex TEF 25"
+  }
+)
+```
+
+Section definitions come from the deck ruleset and are available on `deck.section_definitions`,
+`version.section_definitions`, or through `CardDB.decks.section_definitions(...)`. Use `key`,
+`default?`, `min_cards`, `max_cards`, and `excluded_from_deck_size?` to render sections and
+preflight deck builders before calling `validate` or `publish`.
+
+Entry annotations are JSON with CardDB common keys and app-owned namespaces:
+
+```ruby
+CardDB.decks.add_entry(
+  input: {
+    deckId: deck.id,
+    expectedDraftRevision: deck.draft_revision,
+    datasetKey: "cards",
+    identifier: "CARD-001",
+    quantity: 1,
+    annotations: {
+      common: {
+        notes: "Flex slot",
+        featuredVisible: true,
+        previewVisible: false
+      },
+      apps: {
+        api_application_id => { sideboardPlan: "control" }
+      }
+    }
+  }
+)
+```
+
+Publisher/admin import-format management:
+
+```ruby
+formats = CardDB.decks.import_formats(game_id: "game_uuid", include_archived: false)
+test = CardDB.decks.test_import_format(
+  input: {
+    gameId: "game_uuid",
+    formatKey: "pokemon-live",
+    text: "1 Iron Leaves ex TEF 25"
+  }
+)
+
+created_format = CardDB.decks.create_import_format(
+  input: {
+    gameId: "game_uuid",
+    key: "pokemon-live",
+    name: "Pokemon TCG Live",
+    config: { schemaVersion: 1 }
+  }
+)
+```
+
+OAuth selected-deck and ownership flows:
+
+```ruby
+CardDB.decks.claim(id: deck.id, input: { expectedDraftRevision: deck.draft_revision, appAccess: "RETAIN" })
+CardDB.decks.transfer_ownership(
+  id: deck.id,
+  input: {
+    targetAccountId: "account_uuid",
+    expectedDraftRevision: deck.draft_revision,
+    appAccess: "REVOKE"
+  }
+)
+copy = CardDB.decks.copy(
+  id: deck.id,
+  input: { title: "Testing copy", expectedDraftRevision: deck.draft_revision, appAccess: "RETAIN" }
+)
+
+CardDB.decks.grant_api_application_access(
+  input: { deckId: copy.deck.id, apiApplicationId: "app_uuid", role: "VIEWER" }
+)
+```
+
+Deck validation issues may include rule-specific codes such as `BAN` and `RESTRICTION`.
+Those issues expose metadata such as rule key, matched value, limit, quantity, and field path when available.
+
+Example ruleset JSON fragments for publisher/admin workflows:
+
+```ruby
+rules = {
+  schemaVersion: 1,
+  sections: [{ key: "main", label: "Main Deck", default: true }],
+  deckSize: { min: 60, max: 60 },
+  bans: [
+    {
+      key: "no-banned-cards",
+      label: "Banned cards",
+      identifiers: ["CARD-001"],
+      severity: "BLOCKER"
+    }
+  ],
+  restrictions: [
+    {
+      key: "one-copy-limit",
+      label: "Restricted cards",
+      identifiers: ["CARD-002"],
+      limit: 1,
+      severity: "BLOCKER"
+    }
+  ]
+}
+```
+
+Server-side app-owned and trusted token workflow:
+
+```ruby
+client = CardDB::Client.new(secret_key: ENV.fetch("CARDDB_SECRET_KEY"))
+
+upsert = client.decks.upsert_by_external_ref(
+  input: {
+    externalRef: "metafy:deck:123",
+    publisherSlug: "pokemon-company",
+    gameKey: "pokemon-tcg",
+    title: "Course Deck",
+    accessMode: "AUTHORIZED_TOKEN",
+    discoverability: "UNLISTED",
+    entries: []
+  }
+)
+
+access = client.decks.exchange_access_token(
+  input: {
+    deckId: upsert.deck.id,
+    readMode: "FULL",
+    externalSubject: "user_123"
+  }
+)
+
+deck = client.decks.access(token: access.token)
+
+# Account sessions can also create trusted issuers for a selected API app.
+client.decks.create_access_token_issuer(
+  input: {
+    deckId: upsert.deck.id,
+    apiApplicationId: "app_uuid",
+    readModes: ["FULL"],
+    directSigningKey: {
+      algorithm: "ED25519",
+      keyId: "prod-2026-01",
+      publicKey: "base64_raw_ed25519_public_key"
+    }
+  }
+)
+```
+
 ### Records
 
 ```ruby
@@ -725,8 +1117,18 @@ bundle exec rspec
 
 # Run linter
 bundle exec rubocop
+
+# Run full verification
+bundle exec rake
 ```
 
+Release prep checklist:
+
+- Run `bundle exec rspec`, `bundle exec rubocop`, and `bundle exec rake`.
+- Review `CHANGELOG.md` and the gem version.
+- Build/publish only when explicitly approved; do not publish to RubyGems from docs-only prep.
+- Keep `secret_key` examples server-side only.
+
 ## License
 
 MIT License. See [LICENSE.txt](LICENSE.txt).

data/examples/publisher_content_pipeline.rb

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'carddb'
+
+client = CardDB::Client.new(secret_key: ENV.fetch('CARDDB_SECRET_KEY'))
+publisher_id = ENV.fetch('CARDDB_PUBLISHER_ID')
+game_key = ENV.fetch('CARDDB_GAME_KEY', 'example-tcg')
+
+game = client.games.get_by_key(publisher_id: publisher_id, game_key: game_key, cache: false) ||
+       client.games.create(
+         input: {
+           publisherId: publisher_id,
+           key: game_key,
+           name: 'Example TCG',
+           visibility: 'PRIVATE'
+         }
+       )
+
+client.import_formats.create(
+  input: {
+    gameId: game.id,
+    key: 'ci-json',
+    name: 'CI JSON',
+    config: { schemaVersion: 1 }
+  }
+)
+
+advanced_payload = {
+  datasets: [
+    {
+      name: 'cards',
+      schema: {
+        identifier: { type: 'STRING', isIdentifier: true },
+        name: { type: 'STRING', required: true }
+      },
+      records: [{ identifier: 'CARD-001', name: 'Example Card' }]
+    }
+  ]
+}
+
+preview = client.imports.preview_game(input: { gameId: game.id, data: advanced_payload })
+raise "Import preview blocked: #{preview.warnings.map(&:message).join(', ')}" unless preview.can_proceed?
+
+import_job = client.imports.run_game(
+  input: {
+    gameId: game.id,
+    data: advanced_payload,
+    options: { mode: 'CREATE', onConflict: 'UPDATE' }
+  }
+)
+completed_import = client.imports.wait_for_game_job(import_job.id)
+raise completed_import.error_message unless completed_import.completed?
+
+dataset = client.datasets.get_by_key(game_id: game.id, dataset_key: 'cards')
+raise 'cards dataset was not created' unless dataset
+
+upsert = client.records.upsert_batch(
+  input: {
+    datasetId: dataset.id,
+    records: [{ identifier: 'CARD-002', name: 'Second Example Card' }],
+    options: { mode: 'STRICT', onConflict: 'UPDATE', dryRun: true }
+  }
+)
+
+raise "Upsert validation failed: #{upsert.dry_run_result.errors.map(&:index).join(', ')}" if upsert.dry_run_result&.errors&.any?
+
+delete_preview = client.records.delete_batch(
+  input: {
+    datasetId: dataset.id,
+    reconcileIdentifiers: %w[CARD-001 CARD-002],
+    dryRun: true
+  }
+)
+puts "Would delete #{delete_preview.matched_count} records"
+
+export_job = client.exports.run(input: { datasetId: dataset.id, format: 'JSON' })
+export_result = client.exports.wait_for_job(export_job.id)
+export_with_fresh_url = client.exports.refresh_url(id: export_result.id)
+puts export_with_fresh_url.download_url

data/lib/carddb/client.rb

@@ -24,6 +24,9 @@ module CardDB
     # Create a new CardDB client.
     #
     # @param api_key [String, nil] API key for authentication
+    # @param publishable_key [String, nil] Browser-safe publishable API key
+    # @param secret_key [String, nil] Server-side secret API key for trusted workflows
+    # @param access_token [String, nil] OAuth bearer token for user-authorized requests
     # @param endpoint [String, nil] API endpoint URL
     # @param timeout [Integer, nil] Request timeout in seconds
     # @param open_timeout [Integer, nil] Connection timeout in seconds
@@ -32,8 +35,13 @@ module CardDB
     # @param allowed_publishers [Array<String>, nil] Allowed publisher slugs
     # @param allowed_games [Hash<String, Array<String>>, nil] Allowed games per publisher
     # @param config [Configuration, nil] Configuration object (overrides other params)
+    # rubocop:disable Metrics/ParameterLists
     def initialize(
       api_key: nil,
+      publishable_key: nil,
+      secret_key: nil,
+      access_token: nil,
+      environment: nil,
       endpoint: nil,
       timeout: nil,
       open_timeout: nil,
@@ -46,6 +54,10 @@ module CardDB
       @config = build_config(
         config: config,
         api_key: api_key,
+        publishable_key: publishable_key,
+        secret_key: secret_key,
+        access_token: access_token,
+        environment: environment,
         endpoint: endpoint,
         timeout: timeout,
         open_timeout: open_timeout,
@@ -56,6 +68,7 @@ module CardDB
       )
       @connection = Connection.new(@config)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Access the Publishers resource
     #
@@ -85,6 +98,34 @@ module CardDB
       @records ||= Resources::Records.new(self, connection, config)
     end
 
+    # Access the Import Formats resource
+    #
+    # @return [Resources::ImportFormats]
+    def import_formats
+      @import_formats ||= Resources::ImportFormats.new(self, connection, config)
+    end
+
+    # Access the Imports resource
+    #
+    # @return [Resources::Imports]
+    def imports
+      @imports ||= Resources::Imports.new(self, connection, config)
+    end
+
+    # Access the Exports resource
+    #
+    # @return [Resources::Exports]
+    def exports
+      @exports ||= Resources::Exports.new(self, connection, config)
+    end
+
+    # Access the Files resource
+    #
+    # @return [Resources::Files]
+    def files
+      @files ||= Resources::Files.new(self, connection, config)
+    end
+
     # Access the Decks resource
     #
     # @return [Resources::Decks]
@@ -103,7 +144,7 @@ module CardDB
     #
     # @return [Hash, nil] API key info or nil if no API key
     def me
-      return nil unless config.api_key
+      return nil unless config.effective_api_key || config.access_token
 
       query = QueryBuilder.fetch_me
       data = connection.execute(query, {})