carddb 0.3.15 → 0.4.0

data/lib/carddb/collection.rb

@@ -409,6 +409,16 @@ module CardDB
       end
     end
 
+    # Fetch publisher-defined scan regions for this game.
+    def scan_regions(include_inactive: nil)
+      raise Error, 'No client available to fetch scan regions' unless client
+
+      publisher_slug = publisher&.[]('slug')
+      raise Error, 'Publisher slug not available on this game' unless publisher_slug
+
+      client.games.get_regions(publisher_slug: publisher_slug, game_key: key, include_inactive: include_inactive)
+    end
+
     private
 
     def fetch_datasets(purpose: nil, search: nil, first: nil, after: nil)
@@ -932,6 +942,257 @@ module CardDB
     end
   end
 
+  class ScanJobPayload < Resource
+    def created? = !!data['created']
+
+    def job
+      @job ||= data['job'] ? ScanJob.new(data['job'], client: client) : nil
+    end
+  end
+
+  class ScanBestMatch < Resource
+    def record_id = data['recordId']
+    def score = data['score']
+    def confidence = data['confidence']
+  end
+
+  class ScanCandidate < Resource
+    def record_id = data['recordId']
+    def rank = data['rank']
+    def score = data['score']
+    def confidence = data['confidence']
+    def reasons = data['reasons'] || []
+  end
+
+  class ScanJobError < Resource
+    def code = data['code']
+    def message = data['message']
+  end
+
+  class ScanWebhookState < Resource
+    def configured? = !!data['configured']
+    def url = data['url']
+    def latest_delivery_id = data['latestDeliveryId']
+    def status = data['status']
+    def attempt_count = data['attemptCount']
+    def next_attempt_at = parse_time(data['nextAttemptAt'])
+    def last_attempt_at = parse_time(data['lastAttemptAt'])
+    def delivered_at = parse_time(data['deliveredAt'])
+    def last_status_code = data['lastStatusCode']
+    def last_error = data['lastError']
+  end
+
+  class ScanStageMetrics < Resource
+    def name = data['name']
+    def status = data['status']
+    def duration_ms = data['durationMs']
+    def completed_at = parse_time(data['completedAt'])
+    def details = data['details'] || {}
+  end
+
+  class ScanJobMetrics < Resource
+    def feature_version = data['featureVersion']
+    def candidate_count = data['candidateCount']
+    def confidence_score = data['confidenceScore']
+    def confidence_label = data['confidenceLabel']
+    def timings = data['timings'] || {}
+
+    def stages
+      @stages ||= (data['stages'] || []).map { |stage| ScanStageMetrics.new(stage, client: client) }
+    end
+  end
+
+  class ScanJob < Resource
+    def job_id = data['jobId']
+    def status = data['status']
+    def publisher_slug = data['publisherSlug']
+    def game_key = data['gameKey']
+    def dataset_key = data['datasetKey']
+    def file_id = data['fileId']
+    def client_request_id = data['clientRequestId']
+    def template_id = data['templateId']
+    def template_version_id = data['templateVersionId']
+    def extracted = data['extracted'] || {}
+    def created_at = parse_time(data['createdAt'])
+    def updated_at = parse_time(data['updatedAt'])
+    def started_at = parse_time(data['startedAt'])
+    def completed_at = parse_time(data['completedAt'])
+    def completed? = status.to_s.downcase == 'completed'
+    def failed? = status.to_s.downcase == 'failed'
+    def cancelled? = status.to_s.downcase == 'cancelled'
+
+    def best_match
+      @best_match ||= data['bestMatch'] ? ScanBestMatch.new(data['bestMatch'], client: client) : nil
+    end
+
+    def candidates
+      @candidates ||= (data['candidates'] || []).map { |candidate| ScanCandidate.new(candidate, client: client) }
+    end
+
+    def metrics
+      @metrics ||= data['metrics'] ? ScanJobMetrics.new(data['metrics'], client: client) : nil
+    end
+
+    def webhook
+      @webhook ||= data['webhook'] ? ScanWebhookState.new(data['webhook'], client: client) : nil
+    end
+
+    def error
+      @error ||= data['error'] ? ScanJobError.new(data['error'], client: client) : nil
+    end
+  end
+
+  class ScanFeedbackPayload < Resource
+    def feedback_id = data['feedbackId']
+    def job_id = data['jobId']
+    def status = data['status']
+    def persisted? = !!data['persisted']
+    def correct = data['correct']
+    def predicted_record_id = data['predictedRecordId']
+    def selected_record_id = data['selectedRecordId']
+    def feature_version = data['featureVersion']
+    def message = data['message']
+  end
+
+  class ScanFeedbackMetrics < Resource
+    def total = data['total']
+    def correct = data['correct']
+    def corrected = data['corrected']
+    def unknown = data['unknown']
+    def accuracy = data['accuracy']
+  end
+
+  class ScanFeatureVersionMetrics < Resource
+    def feature_version = data['featureVersion']
+    def job_count = data['jobCount']
+    def completed_jobs = data['completedJobs']
+    def failed_jobs = data['failedJobs']
+    def average_confidence = data['averageConfidence']
+    def average_shortlist_size = data['averageShortlistSize']
+    def feedback_count = data['feedbackCount']
+    def correct_feedback = data['correctFeedback']
+    def corrected_feedback = data['correctedFeedback']
+    def feedback_accuracy = data['feedbackAccuracy']
+  end
+
+  class ScanMetrics < Resource
+    def publisher_slug = data['publisherSlug']
+    def game_key = data['gameKey']
+    def dataset_key = data['datasetKey']
+    def since = parse_time(data['since'])
+    def until = parse_time(data['until'])
+    def generated_at = parse_time(data['generatedAt'])
+    def total_jobs = data['totalJobs']
+    def completed_jobs = data['completedJobs']
+    def failed_jobs = data['failedJobs']
+    def failure_rate = data['failureRate']
+    def average_shortlist_size = data['averageShortlistSize']
+    def confidence_distribution = data['confidenceDistribution'] || {}
+
+    def feedback
+      @feedback ||= data['feedback'] ? ScanFeedbackMetrics.new(data['feedback'], client: client) : nil
+    end
+
+    def feature_versions
+      @feature_versions ||= (data['featureVersions'] || []).map do |version|
+        ScanFeatureVersionMetrics.new(version, client: client)
+      end
+    end
+  end
+
+  class ScanTemplateWarning < Resource
+    def code = data['code']
+    def region = data['region']
+    def message = data['message']
+  end
+
+  class ScanTemplateRegion < Resource
+    def id = data['id']
+    def key = data['key']
+    def label = data['label']
+    def sort_order = data['sortOrder']
+    def shape_type = data['shapeType']
+    def geometry = data['geometry'] || {}
+    def semantic_type = data['semanticType']
+    def extraction_mode = data['extractionMode']
+    def lookup_mode = data['lookupMode']
+    def required? = !!data['isRequired']
+    def weight = data['weight']
+    def config = data['config'] || {}
+  end
+
+  class ScanTemplate < Resource
+    def id = data['id']
+    def key = data['key']
+    def name = data['name']
+    def status = data['status']
+    def version = data['version']
+    def default? = !!data['isDefault']
+    def publisher_slug = data['publisherSlug']
+    def game_key = data['gameKey']
+    def dataset_key = data['datasetKey']
+    def example_file_id = data['exampleFileId']
+    def coordinate_space = data['coordinateSpace']
+    def card_aspect_ratio = data['cardAspectRatio']
+    def notes = data['notes']
+    def config = data['config'] || {}
+    def created_at = parse_time(data['createdAt'])
+    def updated_at = parse_time(data['updatedAt'])
+
+    def regions
+      @regions ||= (data['regions'] || []).map { |region| ScanTemplateRegion.new(region, client: client) }
+    end
+  end
+
+  class ScanTemplateResolution < Resource
+    def template
+      @template ||= data['template'] ? ScanTemplate.new(data['template'], client: client) : nil
+    end
+
+    def warnings
+      @warnings ||= (data['warnings'] || []).map { |warning| ScanTemplateWarning.new(warning, client: client) }
+    end
+  end
+
+  class ScanTemplatePayload < ScanTemplateResolution; end
+
+  class ScanTemplateRegionPreview < Resource
+    def key = data['key']
+    def label = data['label']
+    def semantic_type = data['semanticType']
+    def extraction_mode = data['extractionMode']
+    def lookup_mode = data['lookupMode']
+    def raw_text = data['rawText']
+    def normalized_value = data['normalizedValue']
+    def source = data['source']
+    def status = data['status']
+    def confidence = data['confidence']
+  end
+
+  class ScanTemplatePreview < Resource
+    def message = data['message']
+
+    def warnings
+      @warnings ||= (data['warnings'] || []).map { |warning| ScanTemplateWarning.new(warning, client: client) }
+    end
+
+    def regions
+      @regions ||= (data['regions'] || []).map { |region| ScanTemplateRegionPreview.new(region, client: client) }
+    end
+  end
+
+  class GameScanRegion < Resource
+    def id = data['id']
+    def key = data['key']
+    def name = data['name']
+    def description = data['description']
+    def sort_order = data['sortOrder']
+    def active? = !!data['isActive']
+    def metadata = data['metadata'] || {}
+    def created_at = parse_time(data['createdAt'])
+    def updated_at = parse_time(data['updatedAt'])
+  end
+
   class ObjectField < Resource
     def id = data['id']
     def object_type_id = data['objectTypeId']

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