carddb 0.3.15 → 0.4.0

data/lib/carddb/resources/scan_templates.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module CardDB
+  module Resources
+    # Scan template resource for publisher-managed scan layouts.
+    class ScanTemplates < Base
+      SCOPE_KEY_MAP = {
+        publisher_slug: 'publisherSlug',
+        game_key: 'gameKey',
+        dataset_key: 'datasetKey',
+        template_id: 'templateId',
+        include_archived: 'includeArchived'
+      }.freeze
+
+      TEMPLATE_KEY_MAP = SCOPE_KEY_MAP.merge(
+        is_default: 'isDefault',
+        example_file_id: 'exampleFileId',
+        card_aspect_ratio: 'cardAspectRatio',
+        region_ocr_hints: 'regionOcrHints'
+      ).freeze
+
+      REGION_KEY_MAP = {
+        sort_order: 'sortOrder',
+        shape_type: 'shapeType',
+        semantic_type: 'semanticType',
+        extraction_mode: 'extractionMode',
+        lookup_mode: 'lookupMode',
+        is_required: 'isRequired'
+      }.freeze
+
+      # Resolve the active scan template for a game or dataset scope.
+      def resolve(input = nil, **params)
+        request = scoped_input(graphql_input(coerce_input(input, params), SCOPE_KEY_MAP))
+        key = cache_key('scan_templates', 'resolve', **request)
+
+        with_cache(key, resource: :scan_templates, cache: params[:cache]) do
+          data = connection.execute(QueryBuilder.resolve_scan_template, { input: request })
+          ScanTemplateResolution.new(data['resolveScanTemplate'], client: client)
+        end
+      end
+
+      # List publisher-managed scan templates for a game or dataset scope.
+      def list(input = nil, **params)
+        request = scoped_input(graphql_input(coerce_input(input, params), SCOPE_KEY_MAP))
+        key = cache_key('scan_templates', 'list', **request)
+
+        with_cache(key, resource: :scan_templates, cache: params[:cache]) do
+          data = connection.execute(QueryBuilder.scan_templates, { input: request })
+          (data.dig('scanTemplates', 'templates') || []).map do |template|
+            ScanTemplate.new(template, client: client)
+          end
+        end
+      end
+
+      # Create a publisher-managed scan template. Requires a server-side secret credential.
+      def create(input = nil, **params)
+        config.require_secret_credential!('scan_templates.create')
+
+        request = template_input(coerce_input(input, params))
+        data = connection.execute(QueryBuilder.create_scan_template, { input: request })
+
+        ScanTemplatePayload.new(data['createScanTemplate'], client: client)
+      end
+
+      # Replace a publisher-managed scan template. Requires a server-side secret credential.
+      def update(id = nil, input = nil, **params)
+        config.require_secret_credential!('scan_templates.update')
+
+        id, request_source = update_args(id, input, params)
+        raise ArgumentError, 'scan template id is required' unless id
+
+        request = template_input(request_source)
+        data = connection.execute(QueryBuilder.update_scan_template, { id: id, input: request })
+
+        ScanTemplatePayload.new(data['updateScanTemplate'], client: client)
+      end
+
+      # Validate a draft scan template and normalize provided region OCR hints.
+      def preview(input = nil, **params)
+        request = template_input(coerce_input(input, params))
+        data = connection.execute(QueryBuilder.preview_scan_template, { input: request })
+
+        ScanTemplatePreview.new(data['previewScanTemplate'], client: client)
+      end
+
+      private
+
+      def update_args(id, input, params)
+        if id.is_a?(Hash) && input.nil?
+          source = id.dup
+          template_id = source.delete(:id) || source.delete('id')
+          return [template_id, source]
+        end
+
+        source = coerce_input(input, params)
+        [id || params[:id] || params['id'], source]
+      end
+
+      def template_input(input)
+        request = scoped_input(graphql_input(input, TEMPLATE_KEY_MAP))
+        request['regions'] = Array(request['regions']).map { |region| graphql_input(region, REGION_KEY_MAP) }
+        request
+      end
+
+      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 coerce_input(input, params)
+        params = params.dup
+        input = params.delete(:input) || params.delete('input') if input.nil?
+        (input || {}).merge(params.reject { |key, _value| %i[cache id].include?(key) || %w[cache id].include?(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
+    end
+  end
+end

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.15'
+  VERSION = '0.4.0'
 end

data/lib/carddb.rb

@@ -18,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'
@@ -143,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]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: carddb
 version: !ruby/object:Gem::Version
-  version: 0.3.15
+  version: 0.4.0
 platform: ruby
 authors:
 - CardDB Team
@@ -72,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
@@ -94,6 +95,8 @@ 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://carddb.dev