carddb 0.3.10 → 0.4.0

data/lib/carddb/resources/scans.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module CardDB
+  module Resources
+    # Scan job resource for GraphQL-first card scanning workflows.
+    class Scans < Base
+      TERMINAL_STATUSES = %w[completed failed cancelled].freeze
+
+      CREATE_JOB_KEY_MAP = {
+        publisher_slug: 'publisherSlug',
+        game_key: 'gameKey',
+        dataset_key: 'datasetKey',
+        file_id: 'fileId',
+        client_request_id: 'clientRequestId',
+        template_id: 'templateId',
+        template_version_id: 'templateVersionId',
+        client_ocr_hints: 'clientOcrHints',
+        client_normalization: 'clientNormalization',
+        webhook_url: 'webhookUrl',
+        webhook_secret: 'webhookSecret'
+      }.freeze
+
+      FEEDBACK_KEY_MAP = {
+        job_id: 'jobId',
+        selected_record_id: 'selectedRecordId'
+      }.freeze
+
+      METRICS_KEY_MAP = {
+        publisher_slug: 'publisherSlug',
+        game_key: 'gameKey',
+        dataset_key: 'datasetKey'
+      }.freeze
+
+      # Create a scan job for an already uploaded image file.
+      def create_job(input: nil, **params)
+        request = scoped_input(graphql_input(input || params, CREATE_JOB_KEY_MAP))
+        data = connection.execute(QueryBuilder.create_scan_job, { input: request })
+
+        ScanJobPayload.new(data['createScanJob'], client: client)
+      end
+
+      # Get a scan job and its latest processing result.
+      def get_job(id, cache: nil)
+        key = cache_key('scans', 'get_job', id: id)
+        with_cache(key, resource: :scans, cache: cache) do
+          data = connection.execute(QueryBuilder.scan_job, { id: id })
+          data['scanJob'] ? ScanJob.new(data['scanJob'], client: client) : nil
+        end
+      end
+
+      # Poll a scan job until it reaches a terminal status.
+      def poll_job(id, timeout: 300, interval: 1, backoff: 1.5, max_interval: 10, cancel: nil)
+        started_at = monotonic_time
+        current_interval = [interval.to_f, 0.001].max
+        max_interval = [max_interval.to_f, current_interval].max
+
+        loop do
+          raise Error, 'scan job polling cancelled' if cancel&.call
+
+          job = get_job(id, cache: false)
+          raise NotFoundError, "scan job '#{id}' was not found" unless job
+          return job if TERMINAL_STATUSES.include?(job.status.to_s.downcase)
+
+          remaining = timeout.to_f - (monotonic_time - started_at)
+          raise TimeoutError, "timed out waiting for scan job '#{id}'" if remaining <= 0
+
+          sleep([current_interval, remaining].min)
+          current_interval = [current_interval * [backoff.to_f, 1.0].max, max_interval].min
+        end
+      end
+
+      # Submit correctness feedback for a completed scan job.
+      def submit_feedback(input: nil, **params)
+        request = graphql_input(input || params, FEEDBACK_KEY_MAP)
+        data = connection.execute(QueryBuilder.submit_scan_feedback, { input: request })
+
+        ScanFeedbackPayload.new(data['submitScanFeedback'], client: client)
+      end
+
+      # Aggregate scan metrics for a publisher/game/dataset scope.
+      def metrics(input: nil, **params)
+        request = scoped_input(graphql_input(input || params, METRICS_KEY_MAP))
+        data = connection.execute(QueryBuilder.scan_metrics, { input: request })
+
+        ScanMetrics.new(data['scanMetrics'], client: client)
+      end
+
+      # Verify an X-CardDB-Signature header value for a webhook body.
+      # rubocop:disable Naming/PredicateMethod
+      def verify_webhook_signature(body:, signature:, secret:)
+        expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', secret.to_s, body.to_s)}"
+
+        secure_compare?(signature.to_s.strip.downcase, expected)
+      end
+      # rubocop:enable Naming/PredicateMethod
+
+      private
+
+      def scoped_input(input)
+        publisher_slug = input['publisherSlug'] || resolve_publisher(nil)
+        game_key = input['gameKey'] || resolve_game(nil)
+        validate_access!(publisher_slug, game_key)
+
+        input.merge('publisherSlug' => publisher_slug, 'gameKey' => game_key)
+      end
+
+      def graphql_input(input, key_map)
+        input.each_with_object({}) do |(key, value), output|
+          next if value.nil?
+
+          output[key_map[key.to_sym] || key.to_s] = value
+        end
+      end
+
+      def secure_compare?(left, right)
+        max_length = [left.bytesize, right.bytesize].max
+        diff = left.bytesize ^ right.bytesize
+
+        max_length.times do |index|
+          diff |= (left.getbyte(index) || 0) ^ (right.getbyte(index) || 0)
+        end
+
+        diff.zero?
+      end
+
+      def monotonic_time
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/carddb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CardDB
-  VERSION = '0.3.10'
+  VERSION = '0.4.0'
 end

data/lib/carddb.rb

@@ -8,6 +8,7 @@ require_relative 'carddb/query_builder'
 require_relative 'carddb/filter_builder'
 require_relative 'carddb/collection'
 require_relative 'carddb/cache'
+require_relative 'carddb/deck_tokens'
 require_relative 'carddb/resources/base'
 require_relative 'carddb/resources/publishers'
 require_relative 'carddb/resources/games'
@@ -17,6 +18,8 @@ require_relative 'carddb/resources/import_formats'
 require_relative 'carddb/resources/imports'
 require_relative 'carddb/resources/exports'
 require_relative 'carddb/resources/files'
+require_relative 'carddb/resources/scans'
+require_relative 'carddb/resources/scan_templates'
 require_relative 'carddb/resources/decks'
 require_relative 'carddb/resources/rules'
 require_relative 'carddb/batch'
@@ -142,6 +145,20 @@ module CardDB
       default_client.files
     end
 
+    # Access the Scans resource via the default client.
+    #
+    # @return [Resources::Scans]
+    def scans
+      default_client.scans
+    end
+
+    # Access the Scan Templates resource via the default client.
+    #
+    # @return [Resources::ScanTemplates]
+    def scan_templates
+      default_client.scan_templates
+    end
+
     # Access the Decks resource via the default client.
     #
     # @return [Resources::Decks]
@@ -185,8 +202,8 @@ module CardDB
     #   results[0]  # => Game
     #   results[1]  # => Game
     #   results[2]  # => Publisher
-    def batch(&block)
-      default_client.batch(&block)
+    def batch(&)
+      default_client.batch(&)
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carddb
 version: !ruby/object:Gem::Version
-  version: 0.3.10
+  version: 0.4.0
 platform: ruby
 authors:
 - CardDB Team
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: ed25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -40,7 +54,7 @@ dependencies:
 description: A Ruby client library for interacting with the CardDB GraphQL API. Search
   and fetch card game data with an expressive filter DSL.
 email:
-- support@carddb.xtda.org
+- support@carddb.dev
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -58,6 +72,7 @@ files:
 - examples/filtering.rb
 - examples/pagination.rb
 - examples/publisher_content_pipeline.rb
+- examples/scan_workflow.rb
 - lib/carddb.rb
 - lib/carddb/batch.rb
 - lib/carddb/cache.rb
@@ -65,6 +80,7 @@ files:
 - lib/carddb/collection.rb
 - lib/carddb/configuration.rb
 - lib/carddb/connection.rb
+- lib/carddb/deck_tokens.rb
 - lib/carddb/errors.rb
 - lib/carddb/filter_builder.rb
 - lib/carddb/query_builder.rb
@@ -79,15 +95,17 @@ files:
 - lib/carddb/resources/publishers.rb
 - lib/carddb/resources/records.rb
 - lib/carddb/resources/rules.rb
+- lib/carddb/resources/scan_templates.rb
+- lib/carddb/resources/scans.rb
 - lib/carddb/version.rb
 - scripts/publish.sh
-homepage: https://github.com/xtda/carddb-ruby
+homepage: https://carddb.dev
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/xtda/carddb-ruby
-  source_code_uri: https://github.com/xtda/carddb-ruby
-  changelog_uri: https://github.com/xtda/carddb-ruby/blob/main/CHANGELOG.md
+  homepage_uri: https://carddb.dev
+  source_code_uri: https://github.com/carddb/carddb-ruby
+  changelog_uri: https://github.com/carddb/carddb-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -96,7 +114,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="