carddb 0.3.10 → 0.4.0

data/lib/carddb/query_builder.rb

@@ -680,6 +680,140 @@ module CardDB
         GRAPHQL
       end
 
+      def create_scan_job
+        <<~GRAPHQL
+          mutation CreateScanJob($input: CreateScanJobInput!) {
+            createScanJob(input: $input) {
+              job {
+                #{scan_job_fields}
+              }
+              created
+            }
+          }
+        GRAPHQL
+      end
+
+      def scan_job
+        <<~GRAPHQL
+          query ScanJob($id: UUID!) {
+            scanJob(id: $id) {
+              #{scan_job_fields}
+            }
+          }
+        GRAPHQL
+      end
+
+      def submit_scan_feedback
+        <<~GRAPHQL
+          mutation SubmitScanFeedback($input: SubmitScanFeedbackInput!) {
+            submitScanFeedback(input: $input) {
+              feedbackId
+              jobId
+              status
+              persisted
+              correct
+              predictedRecordId
+              selectedRecordId
+              featureVersion
+              message
+            }
+          }
+        GRAPHQL
+      end
+
+      def scan_metrics
+        <<~GRAPHQL
+          query ScanMetrics($input: ScanMetricsInput!) {
+            scanMetrics(input: $input) {
+              #{scan_metrics_fields}
+            }
+          }
+        GRAPHQL
+      end
+
+      def resolve_scan_template
+        <<~GRAPHQL
+          query ResolveScanTemplate($input: ResolveScanTemplateInput!) {
+            resolveScanTemplate(input: $input) {
+              template {
+                #{scan_template_fields}
+              }
+              warnings {
+                #{scan_template_warning_fields}
+              }
+            }
+          }
+        GRAPHQL
+      end
+
+      def scan_templates
+        <<~GRAPHQL
+          query ScanTemplates($input: ScanTemplatesInput!) {
+            scanTemplates(input: $input) {
+              templates {
+                #{scan_template_fields}
+              }
+            }
+          }
+        GRAPHQL
+      end
+
+      def create_scan_template
+        <<~GRAPHQL
+          mutation CreateScanTemplate($input: SaveScanTemplateInput!) {
+            createScanTemplate(input: $input) {
+              template {
+                #{scan_template_fields}
+              }
+              warnings {
+                #{scan_template_warning_fields}
+              }
+            }
+          }
+        GRAPHQL
+      end
+
+      def update_scan_template
+        <<~GRAPHQL
+          mutation UpdateScanTemplate($id: UUID!, $input: SaveScanTemplateInput!) {
+            updateScanTemplate(id: $id, input: $input) {
+              template {
+                #{scan_template_fields}
+              }
+              warnings {
+                #{scan_template_warning_fields}
+              }
+            }
+          }
+        GRAPHQL
+      end
+
+      def preview_scan_template
+        <<~GRAPHQL
+          mutation PreviewScanTemplate($input: PreviewScanTemplateInput!) {
+            previewScanTemplate(input: $input) {
+              warnings {
+                #{scan_template_warning_fields}
+              }
+              regions {
+                #{scan_template_preview_region_fields}
+              }
+              message
+            }
+          }
+        GRAPHQL
+      end
+
+      def game_scan_regions
+        <<~GRAPHQL
+          query GameScanRegions($publisherSlug: String!, $gameKey: String!, $includeInactive: Boolean) {
+            gameScanRegions(publisherSlug: $publisherSlug, gameKey: $gameKey, includeInactive: $includeInactive) {
+              #{game_scan_region_fields}
+            }
+          }
+        GRAPHQL
+      end
+
       def export_job
         <<~GRAPHQL
           query ExportJob($id: UUID!) {
@@ -2252,6 +2386,181 @@ module CardDB
         FIELDS
       end
 
+      def scan_job_fields
+        <<~FIELDS
+          jobId
+          status
+          publisherSlug
+          gameKey
+          datasetKey
+          fileId
+          clientRequestId
+          templateId
+          templateVersionId
+          bestMatch {
+            recordId
+            score
+            confidence
+          }
+          candidates {
+            recordId
+            rank
+            score
+            confidence
+            reasons
+          }
+          extracted
+          metrics {
+            featureVersion
+            candidateCount
+            confidenceScore
+            confidenceLabel
+            stages {
+              name
+              status
+              durationMs
+              completedAt
+              details
+            }
+            timings
+          }
+          webhook {
+            configured
+            url
+            latestDeliveryId
+            status
+            attemptCount
+            nextAttemptAt
+            lastAttemptAt
+            deliveredAt
+            lastStatusCode
+            lastError
+          }
+          error {
+            code
+            message
+          }
+          createdAt
+          updatedAt
+          startedAt
+          completedAt
+        FIELDS
+      end
+
+      def scan_metrics_fields
+        <<~FIELDS
+          publisherSlug
+          gameKey
+          datasetKey
+          since
+          until
+          generatedAt
+          totalJobs
+          completedJobs
+          failedJobs
+          failureRate
+          averageShortlistSize
+          confidenceDistribution
+          feedback {
+            total
+            correct
+            corrected
+            unknown
+            accuracy
+          }
+          featureVersions {
+            featureVersion
+            jobCount
+            completedJobs
+            failedJobs
+            averageConfidence
+            averageShortlistSize
+            feedbackCount
+            correctFeedback
+            correctedFeedback
+            feedbackAccuracy
+          }
+        FIELDS
+      end
+
+      def scan_template_warning_fields
+        <<~FIELDS
+          code
+          region
+          message
+        FIELDS
+      end
+
+      def scan_template_region_fields
+        <<~FIELDS
+          id
+          key
+          label
+          sortOrder
+          shapeType
+          geometry
+          semanticType
+          extractionMode
+          lookupMode
+          isRequired
+          weight
+          config
+        FIELDS
+      end
+
+      def scan_template_fields
+        <<~FIELDS
+          id
+          key
+          name
+          status
+          version
+          isDefault
+          publisherSlug
+          gameKey
+          datasetKey
+          exampleFileId
+          coordinateSpace
+          cardAspectRatio
+          notes
+          config
+          regions {
+            #{scan_template_region_fields}
+          }
+          createdAt
+          updatedAt
+        FIELDS
+      end
+
+      def scan_template_preview_region_fields
+        <<~FIELDS
+          key
+          label
+          semanticType
+          extractionMode
+          lookupMode
+          rawText
+          normalizedValue
+          source
+          status
+          confidence
+        FIELDS
+      end
+
+      def game_scan_region_fields
+        <<~FIELDS
+          id
+          key
+          name
+          description
+          sortOrder
+          isActive
+          metadata
+          createdAt
+          updatedAt
+        FIELDS
+      end
+
       def import_job_connection_fields
         connection_fields(import_job_fields)
       end

data/lib/carddb/resources/files.rb

@@ -29,6 +29,39 @@ module CardDB
         File.new(data['fileUploadConfirm'], client: client)
       end
 
+      # Request a presigned URL, upload bytes directly to storage, and confirm the file.
+      def upload(
+        filename:,
+        content_type:,
+        body:,
+        size: nil,
+        purpose: nil,
+        is_public: false,
+        entity_type: nil,
+        entity_id: nil,
+        publisher_id: nil,
+        dataset_id: nil
+      )
+        upload_size = size || infer_upload_size(body)
+        raise ArgumentError, 'files.upload requires a positive size or an inferable body size' unless upload_size&.positive?
+
+        upload = request_upload(
+          input: {
+            filename: filename,
+            contentType: content_type,
+            size: upload_size,
+            isPublic: is_public,
+            entityType: entity_type || entity_type_for_purpose(purpose),
+            entityId: entity_id,
+            publisherId: publisher_id,
+            datasetId: dataset_id
+          }.compact
+        )
+
+        put_upload(upload.upload_url, content_type, body)
+        confirm_upload(id: upload.file.id)
+      end
+
       # Delete a file. Requires a server-side secret credential.
       # rubocop:disable Naming/PredicateMethod
       def delete(id:)
@@ -38,6 +71,48 @@ module CardDB
         !!data['fileDelete']
       end
       # rubocop:enable Naming/PredicateMethod
+
+      private
+
+      def put_upload(upload_url, content_type, body)
+        response = Faraday.put(upload_url) do |request|
+          request.headers['Content-Type'] = content_type
+          request.body = body
+        end
+
+        return if response.success?
+
+        raise Error, "file upload failed with #{response.status}: #{response.body}"
+      end
+
+      def infer_upload_size(body)
+        return body.bytesize if body.is_a?(String)
+        return body.bytesize if body.respond_to?(:bytesize)
+        return body.size if body.respond_to?(:size) && body.size.is_a?(Integer)
+        return body.stat.size if body.respond_to?(:stat)
+
+        infer_io_size(body)
+      end
+
+      def infer_io_size(body)
+        return nil unless body.respond_to?(:tell) && body.respond_to?(:seek)
+
+        original_position = body.tell
+        body.seek(0, IO::SEEK_END)
+        size = body.tell
+        body.seek(original_position, IO::SEEK_SET)
+        size
+      rescue IOError, SystemCallError
+        nil
+      end
+
+      def entity_type_for_purpose(purpose)
+        return nil if purpose.nil? || purpose.to_s == 'scan_image'
+        return 'import' if purpose.to_s == 'import'
+        return 'scan_template_example' if purpose.to_s == 'scan_template_example'
+
+        purpose.to_s
+      end
     end
   end
 end

data/lib/carddb/resources/games.rb

@@ -74,6 +74,25 @@ module CardDB
         Game.new(data['gameUpdate'], client: client)
       end
 
+      # Get publisher-defined game region metadata for scan-capable clients.
+      def get_regions(publisher_slug: nil, game_key: nil, include_inactive: nil, cache: nil)
+        resolved_publisher = resolve_publisher(publisher_slug)
+        resolved_game = resolve_game(game_key)
+        validate_access!(resolved_publisher, resolved_game)
+
+        variables = build_variables(
+          publisherSlug: resolved_publisher,
+          gameKey: resolved_game,
+          includeInactive: include_inactive
+        )
+        key = cache_key('games', 'get_regions', **variables)
+
+        with_cache(key, resource: :games, cache: cache) do
+          data = connection.execute(QueryBuilder.game_scan_regions, variables)
+          (data['gameScanRegions'] || []).map { |region| GameScanRegion.new(region, client: client) }
+        end
+      end
+
       # Search for games
       #
       # @param publisher_slug [String, nil] Filter by publisher slug

data/lib/carddb/resources/records.rb

@@ -18,9 +18,9 @@ module CardDB
         before: nil,
         validate_schema: nil,
         cache: nil,
-        &block
+        &
       )
-        final_filter = block_given? ? FilterBuilder.build(&block) : filter
+        final_filter = block_given? ? FilterBuilder.build(&) : filter
         query = QueryBuilder.list_dataset_records(
           dataset_id: dataset_id,
           filter: final_filter,
@@ -206,7 +206,7 @@ module CardDB
         after: nil,
         validate_schema: nil,
         include_pricing: false,
-        &block
+        &
       )
         resolved_publisher = resolve_publisher(publisher_slug)
         resolved_game = resolve_game(game_key)
@@ -215,7 +215,7 @@ module CardDB
 
         # Build filter from DSL block if provided
         final_filter = if block_given?
-                         FilterBuilder.build(&block)
+                         FilterBuilder.build(&)
                        else
                          filter
                        end

data/lib/carddb/resources/rules.rb

@@ -27,22 +27,22 @@ module CardDB
       #
       # @param dataset_key [String] Rules dataset key (defaults to "rules")
       # @return [Collection<Record>] Collection of rule records
-      def list(dataset_key: 'rules', **options, &block)
-        search_records(dataset_key: dataset_key, **options, &block)
+      def list(dataset_key: 'rules', **, &)
+        search_records(dataset_key: dataset_key, **, &)
       end
 
       # List deck/game formats from the game's formats dataset.
       #
       # @param dataset_key [String] Formats dataset key (defaults to "formats")
       # @return [Collection<Record>] Collection of format records
-      def formats(dataset_key: 'formats', **options, &block)
-        search_records(dataset_key: dataset_key, **options, &block)
+      def formats(dataset_key: 'formats', **, &)
+        search_records(dataset_key: dataset_key, **, &)
       end
 
       private
 
-      def search_records(dataset_key:, **options, &block)
-        client.records.search(dataset_key: dataset_key, **options, &block)
+      def search_records(dataset_key:, **, &)
+        client.records.search(dataset_key: dataset_key, **, &)
       end
     end
   end

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