carddb 0.3.0 → 0.3.5

data/lib/carddb/resources/datasets.rb

@@ -4,6 +4,79 @@ module CardDB
   module Resources
     # Datasets resource for searching, fetching, and getting schema
     class Datasets < Base
+      # List datasets for a publisher-management context.
+      def list(publisher_id:, game_id: nil, purpose: nil, first: nil, after: nil, include_archived: nil, cache: nil)
+        query = QueryBuilder.list_datasets(
+          publisher_id: publisher_id,
+          game_id: game_id,
+          purpose: purpose,
+          first: first,
+          after: after,
+          include_archived: include_archived
+        )
+        variables = build_variables(
+          publisherId: publisher_id,
+          gameId: game_id,
+          purpose: purpose,
+          first: first,
+          after: after,
+          includeArchived: include_archived
+        )
+        key = cache_key('datasets', 'list', **variables)
+
+        data = with_cache(key, resource: :datasets, cache: cache) { connection.execute(query, variables) }
+
+        Collection.new(
+          data['datasets'],
+          item_class: Dataset,
+          next_page_loader: lambda { |cursor|
+            list(
+              publisher_id: publisher_id,
+              game_id: game_id,
+              purpose: purpose,
+              first: first,
+              after: cursor,
+              include_archived: include_archived,
+              cache: cache
+            )
+          },
+          client: client
+        )
+      end
+
+      # Get a dataset by game ID and stable dataset key.
+      def get_by_key(game_id:, dataset_key:, publisher_id: nil, cache: nil)
+        key = cache_key(
+          'datasets',
+          'get_by_key',
+          publisher_id: publisher_id,
+          game_id: game_id,
+          dataset_key: dataset_key
+        )
+        with_cache(key, resource: :datasets, cache: cache) do
+          query = QueryBuilder.dataset(publisher_id: publisher_id, game_id: game_id, dataset_key: dataset_key)
+          variables = build_variables(publisherId: publisher_id, gameId: game_id, datasetKey: dataset_key)
+          data = connection.execute(query, variables)
+
+          data['dataset'] ? Dataset.new(data['dataset'], client: client) : nil
+        end
+      end
+
+      # Fetch only the schema portion for a dataset.
+      def get_schema(id: nil, publisher_id: nil, game_id: nil, dataset_key: nil, cache: nil)
+        dataset = if id
+                    get_by_id_for_management(id, cache: cache)
+                  else
+                    get_by_key(
+                      publisher_id: publisher_id,
+                      game_id: game_id,
+                      dataset_key: dataset_key,
+                      cache: cache
+                    )
+                  end
+        dataset&.schema
+      end
+
       # Search for datasets
       #
       # @param publisher_slug [String, nil] Filter by publisher slug
@@ -127,6 +200,18 @@ module CardDB
         )
         dataset&.schema
       end
+
+      private
+
+      def get_by_id_for_management(id, cache: nil)
+        key = cache_key('datasets', 'get_schema', id: id)
+        with_cache(key, resource: :datasets, cache: cache) do
+          query = QueryBuilder.dataset(id: id)
+          data = connection.execute(query, { id: id })
+
+          data['dataset'] ? Dataset.new(data['dataset'], client: client) : nil
+        end
+      end
     end
   end
 end

data/lib/carddb/resources/exports.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Publisher dataset export jobs resource.
+    class Exports < Base
+      # Start an async dataset export. Requires a server-side secret credential.
+      def run(input:)
+        config.require_secret_credential!('exports.run')
+
+        data = connection.execute(QueryBuilder.dataset_export, { input: input })
+        ExportJob.new(data['datasetExport'], client: client)
+      end
+      alias create run
+
+      # Fetch one export job.
+      def get_job(id, cache: nil)
+        key = cache_key('exports', 'get_job', id: id)
+        with_cache(key, resource: :exports, cache: cache) do
+          data = connection.execute(QueryBuilder.export_job, { id: id })
+          data['exportJob'] ? ExportJob.new(data['exportJob'], client: client) : nil
+        end
+      end
+
+      # List export jobs for a publisher, optionally filtered by game, dataset, or status.
+      def list_jobs(publisher_id:, game_id: nil, dataset_id: nil, status: nil, first: nil, after: nil, cache: nil)
+        query = QueryBuilder.export_jobs(
+          publisher_id: publisher_id,
+          game_id: game_id,
+          dataset_id: dataset_id,
+          status: status,
+          first: first,
+          after: after
+        )
+        variables = build_variables(
+          publisherId: publisher_id,
+          gameId: game_id,
+          datasetId: dataset_id,
+          status: status,
+          first: first,
+          after: after
+        )
+        key = cache_key('exports', 'list_jobs', **variables)
+
+        data = with_cache(key, resource: :exports, cache: cache) { connection.execute(query, variables) }
+
+        Collection.new(
+          data['exportJobs'],
+          item_class: ExportJob,
+          next_page_loader: lambda { |cursor|
+            list_jobs(
+              publisher_id: publisher_id,
+              game_id: game_id,
+              dataset_id: dataset_id,
+              status: status,
+              first: first,
+              after: cursor,
+              cache: cache
+            )
+          },
+          client: client
+        )
+      end
+
+      # Refresh the signed download URL for a completed export job.
+      def refresh_url(id:)
+        data = connection.execute(QueryBuilder.export_job_refresh_url, { id: id })
+        ExportJob.new(data['exportJobRefreshUrl'], client: client)
+      end
+
+      # Cancel a pending or processing export job. Requires a server-side secret credential.
+      def cancel(id:)
+        config.require_secret_credential!('exports.cancel')
+
+        data = connection.execute(QueryBuilder.export_job_cancel, { id: id })
+        ExportJob.new(data['exportJobCancel'], client: client)
+      end
+
+      # Poll an export job until completion or failure.
+      def wait_for_job(id, interval: 1, timeout: 300)
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        loop do
+          job = get_job(id, cache: false)
+          raise Error, "Export job '#{id}' was not found" unless job
+          return job if job.completed? || job.failed?
+
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+          raise Error, "Timed out waiting for export job '#{id}'" if elapsed >= timeout
+
+          sleep interval
+        end
+      end
+    end
+  end
+end

data/lib/carddb/resources/files.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # File upload helper resource.
+    class Files < Base
+      # Get one file by ID.
+      def get(id, cache: nil)
+        key = cache_key('files', 'get', id: id)
+        with_cache(key, resource: :files, cache: cache) do
+          data = connection.execute(QueryBuilder.file, { id: id })
+          data['file'] ? File.new(data['file'], client: client) : nil
+        end
+      end
+
+      # Request a presigned URL for direct upload. Requires a server-side secret credential.
+      def request_upload(input:)
+        config.require_secret_credential!('files.request_upload')
+
+        data = connection.execute(QueryBuilder.file_upload_request, { input: input })
+        PresignedUpload.new(data['fileUploadRequest'], client: client)
+      end
+
+      # Confirm that a presigned upload completed. Requires a server-side secret credential.
+      def confirm_upload(id:)
+        config.require_secret_credential!('files.confirm_upload')
+
+        data = connection.execute(QueryBuilder.file_upload_confirm, { id: id })
+        File.new(data['fileUploadConfirm'], client: client)
+      end
+
+      # Delete a file. Requires a server-side secret credential.
+      # rubocop:disable Naming/PredicateMethod
+      def delete(id:)
+        config.require_secret_credential!('files.delete')
+
+        data = connection.execute(QueryBuilder.file_delete, { id: id })
+        !!data['fileDelete']
+      end
+      # rubocop:enable Naming/PredicateMethod
+    end
+  end
+end

data/lib/carddb/resources/games.rb

@@ -4,6 +4,76 @@ module CardDB
   module Resources
     # Games resource for searching and fetching games
     class Games < Base
+      # List games for a publisher-management context.
+      def list(publisher_id:, first: nil, after: nil, include_archived: nil, cache: nil)
+        query = QueryBuilder.list_games(
+          publisher_id: publisher_id,
+          first: first,
+          after: after,
+          include_archived: include_archived
+        )
+        variables = build_variables(
+          publisherId: publisher_id,
+          first: first,
+          after: after,
+          includeArchived: include_archived
+        )
+        key = cache_key('games', 'list', **variables)
+
+        data = with_cache(key, resource: :games, cache: cache) { connection.execute(query, variables) }
+
+        Collection.new(
+          data['games'],
+          item_class: Game,
+          next_page_loader: lambda { |cursor|
+            list(publisher_id: publisher_id, first: first, after: cursor, include_archived: include_archived, cache: cache)
+          },
+          client: client
+        )
+      end
+
+      # Get a publisher-managed game by stable key.
+      def get_by_key(game_key:, publisher_id: nil, publisher_slug: nil, cache: nil)
+        key = cache_key('games', 'get_by_key', publisher_id: publisher_id, publisher_slug: publisher_slug,
+                                               game_key: game_key)
+        with_cache(key, resource: :games, cache: cache) do
+          query = QueryBuilder.game(publisher_id: publisher_id, publisher_slug: publisher_slug, game_key: game_key)
+          variables = build_variables(publisherId: publisher_id, publisherSlug: publisher_slug, gameKey: game_key)
+          data = connection.execute(query, variables)
+
+          data['game'] ? Game.new(data['game'], client: client) : nil
+        end
+      end
+
+      # Get a publisher-managed game by slug.
+      def get_by_slug(game_slug:, publisher_id: nil, publisher_slug: nil, cache: nil)
+        key = cache_key('games', 'get_by_slug', publisher_id: publisher_id, publisher_slug: publisher_slug,
+                                                game_slug: game_slug)
+        with_cache(key, resource: :games, cache: cache) do
+          query = QueryBuilder.game(publisher_id: publisher_id, publisher_slug: publisher_slug, game_slug: game_slug)
+          variables = build_variables(publisherId: publisher_id, publisherSlug: publisher_slug, gameSlug: game_slug)
+          data = connection.execute(query, variables)
+
+          data['game'] ? Game.new(data['game'], client: client) : nil
+        end
+      end
+
+      # Create a publisher-managed game. Requires a server-side secret credential.
+      def create(input:)
+        config.require_secret_credential!('games.create')
+
+        data = connection.execute(QueryBuilder.create_game, { input: input })
+        Game.new(data['gameCreate'], client: client)
+      end
+
+      # Update a publisher-managed game. Requires a server-side secret credential.
+      def update(id:, input:)
+        config.require_secret_credential!('games.update')
+
+        data = connection.execute(QueryBuilder.update_game, { id: id, input: input })
+        Game.new(data['gameUpdate'], client: client)
+      end
+
       # Search for games
       #
       # @param publisher_slug [String, nil] Filter by publisher slug

data/lib/carddb/resources/import_formats.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Publisher-managed import format resource.
+    class ImportFormats < Base
+      # List import formats scoped by publisher or game.
+      def list(publisher_id: nil, game_id: nil, include_archived: nil, first: nil, after: nil, cache: nil)
+        query = QueryBuilder.deck_import_formats(
+          publisher_id: publisher_id,
+          game_id: game_id,
+          include_archived: include_archived,
+          first: first,
+          after: after
+        )
+        variables = build_variables(
+          publisherId: publisher_id,
+          gameId: game_id,
+          includeArchived: include_archived,
+          first: first,
+          after: after
+        )
+        key = cache_key('import_formats', 'list', **variables)
+
+        data = with_cache(key, resource: :import_formats, cache: cache) do
+          connection.execute(query, variables)
+        end
+
+        Collection.new(
+          data['deckImportFormats'],
+          item_class: DeckImportFormatDefinition,
+          next_page_loader: lambda { |cursor|
+            list(
+              publisher_id: publisher_id,
+              game_id: game_id,
+              include_archived: include_archived,
+              first: first,
+              after: cursor,
+              cache: cache
+            )
+          },
+          client: client
+        )
+      end
+
+      # Get one import format by UUID.
+      def get(id, cache: nil)
+        key = cache_key('import_formats', 'get', id: id)
+        with_cache(key, resource: :import_formats, cache: cache) do
+          data = connection.execute(QueryBuilder.deck_import_format, { id: id })
+          data['deckImportFormat'] ? DeckImportFormatDefinition.new(data['deckImportFormat'], client: client) : nil
+        end
+      end
+
+      # Get one import format by game ID and stable key.
+      def get_by_key(game_id:, key:, cache: nil)
+        cache_key_value = cache_key('import_formats', 'get_by_key', game_id: game_id, key: key)
+        with_cache(cache_key_value, resource: :import_formats, cache: cache) do
+          data = connection.execute(QueryBuilder.deck_import_format, { gameId: game_id, key: key })
+          data['deckImportFormat'] ? DeckImportFormatDefinition.new(data['deckImportFormat'], client: client) : nil
+        end
+      end
+
+      # Preview parsing and record resolution for a configured import format.
+      def test(input:)
+        data = connection.execute(QueryBuilder.deck_import_format_test, { input: input })
+        DeckImportFormatTestPayload.new(data['deckImportFormatTest'], client: client)
+      end
+
+      # Create an import format. Requires a server-side secret credential.
+      def create(input:)
+        config.require_secret_credential!('import_formats.create')
+
+        data = connection.execute(QueryBuilder.create_deck_import_format, { input: input })
+        DeckImportFormatDefinition.new(data['deckImportFormatCreate'], client: client)
+      end
+
+      # Update an import format. Requires a server-side secret credential.
+      def update(id:, input:)
+        config.require_secret_credential!('import_formats.update')
+
+        data = connection.execute(QueryBuilder.update_deck_import_format, { id: id, input: input })
+        DeckImportFormatDefinition.new(data['deckImportFormatUpdate'], client: client)
+      end
+
+      # Archive an import format. Requires a server-side secret credential.
+      def archive(id:)
+        config.require_secret_credential!('import_formats.archive')
+
+        data = connection.execute(QueryBuilder.archive_deck_import_format, { id: id })
+        DeckImportFormatDefinition.new(data['deckImportFormatArchive'], client: client)
+      end
+
+      # Restore an archived import format. Requires a server-side secret credential.
+      def unarchive(id:)
+        config.require_secret_credential!('import_formats.unarchive')
+
+        data = connection.execute(QueryBuilder.unarchive_deck_import_format, { id: id })
+        DeckImportFormatDefinition.new(data['deckImportFormatUnarchive'], client: client)
+      end
+    end
+  end
+end

data/lib/carddb/resources/imports.rb

@@ -0,0 +1,225 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Publisher import job resource for single-dataset and game-level imports.
+    class Imports < Base
+      EMPTY_CONNECTION = {
+        'totalCount' => 0,
+        'pageInfo' => {
+          'hasNextPage' => false,
+          'hasPreviousPage' => false,
+          'startCursor' => nil,
+          'endCursor' => nil
+        },
+        'edges' => []
+      }.freeze
+
+      # Preview a single-dataset import source without writing records or schema.
+      def preview(input:)
+        data = connection.execute(QueryBuilder.dataset_import_preview, { input: input })
+        DatasetImportPreviewResult.new(data['datasetImportPreview'], client: client)
+      end
+
+      # Validate a single-dataset import source with dry-run enforced.
+      def validate(input:)
+        data = connection.execute(QueryBuilder.dataset_import_validate, { input: input })
+        BulkImportResult.new(data['datasetImportValidate'], client: client)
+      end
+
+      # Start an async single-dataset import from fileId, data, or sourceUrl.
+      def run(input:)
+        config.require_secret_credential!('imports.run')
+
+        query, response_key = import_query_for(input)
+        data = connection.execute(query, { input: input })
+        ImportJob.new(data[response_key], client: client)
+      end
+
+      # Fetch one single-dataset import job.
+      def get_job(id, cache: nil)
+        key = cache_key('imports', 'get_job', id: id)
+        with_cache(key, resource: :imports, cache: cache) do
+          data = connection.execute(QueryBuilder.import_job, { id: id })
+          data['importJob'] ? ImportJob.new(data['importJob'], client: client) : nil
+        end
+      end
+
+      # List single-dataset import jobs for a publisher.
+      def list_jobs(publisher_id:, dataset_id: nil, status: nil, first: nil, after: nil, cache: nil)
+        query = QueryBuilder.import_jobs(
+          publisher_id: publisher_id,
+          dataset_id: dataset_id,
+          status: status,
+          first: first,
+          after: after
+        )
+        variables = build_variables(
+          publisherId: publisher_id,
+          datasetId: dataset_id,
+          status: status,
+          first: first,
+          after: after
+        )
+        key = cache_key('imports', 'list_jobs', **variables)
+
+        data = with_cache(key, resource: :imports, cache: cache) { connection.execute(query, variables) }
+
+        Collection.new(
+          data['importJobs'],
+          item_class: ImportJob,
+          next_page_loader: lambda { |cursor|
+            list_jobs(
+              publisher_id: publisher_id,
+              dataset_id: dataset_id,
+              status: status,
+              first: first,
+              after: cursor,
+              cache: cache
+            )
+          },
+          client: client
+        )
+      end
+
+      # Cancel a pending or processing single-dataset import job.
+      def cancel_job(id:)
+        config.require_secret_credential!('imports.cancel_job')
+
+        data = connection.execute(QueryBuilder.import_job_cancel, { id: id })
+        ImportJob.new(data['importJobCancel'], client: client)
+      end
+
+      # List structured logs for one single-dataset import job.
+      def list_job_logs(import_job_id:, level: nil, dataset_key: nil, first: nil, after: nil, cache: nil)
+        query = QueryBuilder.import_job_logs(level: level, dataset_key: dataset_key, first: first, after: after)
+        variables = build_variables(
+          importJobId: import_job_id,
+          level: level,
+          datasetKey: dataset_key,
+          first: first,
+          after: after
+        )
+        key = cache_key('imports', 'list_job_logs', **variables)
+
+        data = with_cache(key, resource: :imports, cache: cache) { connection.execute(query, variables) }
+        logs = data.dig('importJob', 'logs') || EMPTY_CONNECTION
+
+        Collection.new(
+          logs,
+          item_class: ImportJobLog,
+          next_page_loader: lambda { |cursor|
+            list_job_logs(
+              import_job_id: import_job_id,
+              level: level,
+              dataset_key: dataset_key,
+              first: first,
+              after: cursor,
+              cache: cache
+            )
+          },
+          client: client
+        )
+      end
+
+      # Poll a single-dataset import job until completion or failure.
+      def wait_for_job(id, interval: 1, timeout: 300)
+        wait_until_terminal(id, interval: interval, timeout: timeout) do
+          get_job(id, cache: false)
+        end
+      end
+
+      # Preview an advanced game-level import source without writing records or schema.
+      def preview_game(input:)
+        data = connection.execute(QueryBuilder.game_import_preview, { input: input })
+        GameImportPreview.new(data['gameImportPreview'], client: client)
+      end
+
+      # Start an async advanced game-level import from fileId, data, or sourceUrl.
+      def run_game(input:)
+        config.require_secret_credential!('imports.run_game')
+
+        query, response_key = game_import_query_for(input)
+        data = connection.execute(query, { input: input })
+        GameImportJob.new(data[response_key], client: client)
+      end
+
+      # Fetch one advanced game-level import job.
+      def get_game_job(id, cache: nil)
+        key = cache_key('imports', 'get_game_job', id: id)
+        with_cache(key, resource: :imports, cache: cache) do
+          data = connection.execute(QueryBuilder.game_import_job, { id: id })
+          data['gameImportJob'] ? GameImportJob.new(data['gameImportJob'], client: client) : nil
+        end
+      end
+
+      # List advanced game-level import jobs.
+      def list_game_jobs(game_id:, status: nil, first: nil, after: nil, cache: nil)
+        query = QueryBuilder.game_import_jobs(game_id: game_id, status: status, first: first, after: after)
+        variables = build_variables(gameId: game_id, status: status, first: first, after: after)
+        key = cache_key('imports', 'list_game_jobs', **variables)
+
+        data = with_cache(key, resource: :imports, cache: cache) { connection.execute(query, variables) }
+
+        Collection.new(
+          data['gameImportJobs'],
+          item_class: GameImportJob,
+          next_page_loader: lambda { |cursor|
+            list_game_jobs(game_id: game_id, status: status, first: first, after: cursor, cache: cache)
+          },
+          client: client
+        )
+      end
+
+      # Cancel a pending or processing advanced game-level import job.
+      def cancel_game_job(id:)
+        config.require_secret_credential!('imports.cancel_game_job')
+
+        data = connection.execute(QueryBuilder.game_import_job_cancel, { id: id })
+        GameImportJob.new(data['gameImportJobCancel'], client: client)
+      end
+
+      # Poll an advanced game-level import job until completion or failure.
+      def wait_for_game_job(id, interval: 1, timeout: 300)
+        wait_until_terminal(id, interval: interval, timeout: timeout) do
+          get_game_job(id, cache: false)
+        end
+      end
+
+      private
+
+      def import_query_for(input)
+        return [QueryBuilder.dataset_import_from_file, 'datasetImportFromFile'] if input_value(input, :fileId, 'fileId')
+        return [QueryBuilder.dataset_import_from_url, 'datasetImportFromUrl'] if input_value(input, :sourceUrl, 'sourceUrl')
+
+        [QueryBuilder.dataset_import_from_payload, 'datasetImportFromPayload']
+      end
+
+      def game_import_query_for(input)
+        return [QueryBuilder.game_import_from_file, 'gameImportFromFile'] if input_value(input, :fileId, 'fileId')
+        return [QueryBuilder.game_import_from_url, 'gameImportFromUrl'] if input_value(input, :sourceUrl, 'sourceUrl')
+
+        [QueryBuilder.game_import_from_payload, 'gameImportFromPayload']
+      end
+
+      def input_value(input, *keys)
+        keys.find { |key| input.key?(key) && input[key] }
+      end
+
+      def wait_until_terminal(id, interval:, timeout:)
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        loop do
+          job = yield
+          raise Error, "Job '#{id}' was not found" unless job
+          return job if job.completed? || job.failed?
+
+          elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+          raise Error, "Timed out waiting for job '#{id}'" if elapsed >= timeout
+
+          sleep interval
+        end
+      end
+    end
+  end
+end