carddb 0.3.10 → 0.4.0

data/lib/carddb/client.rb

@@ -126,6 +126,20 @@ module CardDB
       @files ||= Resources::Files.new(self, connection, config)
     end
 
+    # Access the Scans resource
+    #
+    # @return [Resources::Scans]
+    def scans
+      @scans ||= Resources::Scans.new(self, connection, config)
+    end
+
+    # Access the Scan Templates resource
+    #
+    # @return [Resources::ScanTemplates]
+    def scan_templates
+      @scan_templates ||= Resources::ScanTemplates.new(self, connection, config)
+    end
+
     # Access the Decks resource
     #
     # @return [Resources::Decks]

data/lib/carddb/collection.rb

@@ -30,8 +30,8 @@ module CardDB
     end
 
     # Iterate over items
-    def each(&block)
-      items.each(&block)
+    def each(&)
+      items.each(&)
     end
 
     # Check if there are more pages
@@ -242,8 +242,8 @@ module CardDB
       data
     end
 
-    def to_json(*args)
-      data.to_json(*args)
+    def to_json(*)
+      data.to_json(*)
     end
 
     private
@@ -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)
@@ -581,7 +591,7 @@ module CardDB
     # @yield [FilterBuilder] Optional block for filter DSL
     # @return [Collection<Record>] Collection of records
     # @raise [CardDB::Error] If no client is available
-    def records(first: nil, filter: nil, include_pricing: false, &block)
+    def records(first: nil, filter: nil, include_pricing: false, &)
       raise Error, 'No client available to fetch records' unless client
 
       publisher_slug = publisher&.[]('slug')
@@ -597,7 +607,7 @@ module CardDB
         first: first,
         filter: filter,
         include_pricing: include_pricing,
-        &block
+        &
       )
     end
 
@@ -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/configuration.rb

@@ -32,7 +32,7 @@ module CardDB
   #   end
   class Configuration
     # Default API endpoint
-    DEFAULT_ENDPOINT = 'https://carddb.xtda.org/query'
+    DEFAULT_ENDPOINT = 'https://carddb.dev/query'
 
     # Default timeouts in seconds
     DEFAULT_TIMEOUT = 30

data/lib/carddb/deck_tokens.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'base64'
+require 'ed25519'
+require 'json'
+require 'openssl'
+
+module CardDB
+  # Server-side helpers for minting direct signed deck access tokens.
+  module DeckTokens
+    TOKEN_USE = 'carddb.deck_access.v1'
+    AUDIENCE = 'carddb.deck_access'
+    ED25519_PKCS8_PREFIX = [
+      '302e020100300506032b657004220420'
+    ].pack('H*').freeze
+    READ_MODES = {
+      'PUBLIC' => 'public',
+      'EMBED' => 'embed',
+      'FULL' => 'full'
+    }.freeze
+    private_constant :READ_MODES
+
+    class << self
+      # Generate an Ed25519 keypair for CardDB direct deck access token signing.
+      #
+      # @return [Hash{Symbol => String}] Includes a PEM private key and the base64-encoded raw public key
+      def generate_direct_access_key_pair
+        signing_key = Ed25519::SigningKey.generate
+
+        {
+          private_key_pem: seed_to_pem(signing_key.to_bytes),
+          public_key_base64: Base64.strict_encode64(signing_key.verify_key.to_bytes)
+        }
+      end
+
+      # Sign a direct deck access token that CardDB can verify with the issuer public key.
+      #
+      # @param issuer_id [String]
+      # @param deck_id [String]
+      # @param api_application_id [String]
+      # @param key_id [String]
+      # @param private_key [OpenSSL::PKey::PKey, String] Ed25519 private key as an OpenSSL key or PEM/DER string
+      # @param read_mode [String] PUBLIC, EMBED, or FULL
+      # @param subject [String, nil]
+      # @param token_id [String, nil]
+      # @param issued_at [Time]
+      # @param expires_at [Time]
+      # @return [String]
+      # @raise [ArgumentError]
+      def sign_direct_access_token(issuer_id:, deck_id:, api_application_id:, key_id:, private_key:, read_mode:,
+                                   expires_at:, subject: nil, token_id: nil, issued_at: Time.now)
+        issued_at, expires_at = validate_signing_input!(
+          issuer_id: issuer_id,
+          deck_id: deck_id,
+          api_application_id: api_application_id,
+          key_id: key_id,
+          issued_at: issued_at,
+          expires_at: expires_at
+        )
+        normalized_read_mode = normalize_read_mode!(read_mode)
+        key = normalize_private_key!(private_key)
+        header = { alg: 'EdDSA', kid: key_id.strip }
+        payload = build_payload(
+          issuer_id: issuer_id,
+          deck_id: deck_id,
+          api_application_id: api_application_id,
+          read_mode: normalized_read_mode,
+          subject: subject,
+          token_id: token_id,
+          issued_at: issued_at,
+          expires_at: expires_at
+        )
+
+        encoded_header = base64url_encode(JSON.generate(header))
+        encoded_payload = base64url_encode(JSON.generate(payload))
+        signing_input = "#{encoded_header}.#{encoded_payload}"
+        signature = sign_with_private_key(key, signing_input)
+
+        [encoded_header, encoded_payload, base64url_encode(signature)].join('.')
+      end
+
+      private
+
+      def validate_signing_input!(issuer_id:, deck_id:, api_application_id:, key_id:, issued_at:, expires_at:)
+        validate_required_string!(issuer_id, 'issuer_id')
+        validate_required_string!(deck_id, 'deck_id')
+        validate_required_string!(api_application_id, 'api_application_id')
+        validate_required_string!(key_id, 'key_id')
+
+        issued_at = normalize_time!(issued_at, 'issued_at')
+        expires_at = normalize_time!(expires_at, 'expires_at')
+        raise ArgumentError, 'expires_at must be after issued_at' unless expires_at > issued_at
+
+        [issued_at, expires_at]
+      end
+
+      def build_payload(issuer_id:, deck_id:, api_application_id:, read_mode:, subject:, token_id:, issued_at:,
+                        expires_at:)
+        payload = {
+          token_use: TOKEN_USE,
+          deck_id: deck_id.strip,
+          app_id: api_application_id.strip,
+          read_mode: read_mode,
+          iss: issuer_id.strip,
+          aud: AUDIENCE,
+          iat: issued_at.to_i,
+          exp: expires_at.to_i
+        }
+        add_optional_claim!(payload, :sub, subject)
+        add_optional_claim!(payload, :jti, token_id)
+        payload
+      end
+
+      def add_optional_claim!(payload, key, value)
+        trimmed = value&.strip
+        payload[key] = trimmed if trimmed&.length&.positive?
+      end
+
+      def validate_required_string!(value, name)
+        raise ArgumentError, "#{name} is required" unless value.is_a?(String) && !value.strip.empty?
+      end
+
+      def normalize_time!(value, name)
+        raise ArgumentError, "#{name} must be a Time" unless value.is_a?(Time)
+
+        value
+      end
+
+      def normalize_read_mode!(read_mode)
+        READ_MODES.fetch(read_mode.to_s.upcase) do
+          raise ArgumentError, 'read_mode must be PUBLIC, EMBED, or FULL'
+        end
+      end
+
+      def normalize_private_key!(private_key)
+        return private_key if private_key.is_a?(OpenSSL::PKey::PKey)
+
+        if private_key.is_a?(String)
+          key = try_read_openssl_private_key(private_key)
+          return key if key
+
+          seed = try_extract_seed(private_key)
+          return Ed25519::SigningKey.new(seed) if seed
+        end
+
+        raise ArgumentError, 'private_key must be an Ed25519 private key'
+      end
+
+      def try_read_openssl_private_key(value)
+        key = OpenSSL::PKey.read(value)
+        key.sign(nil, 'carddb-test')
+        key
+      rescue OpenSSL::OpenSSLError, ArgumentError
+        nil
+      end
+
+      def try_extract_seed(value)
+        der = decode_private_key_der(value)
+        return nil unless der.bytesize == ED25519_PKCS8_PREFIX.bytesize + Ed25519::KEY_SIZE
+        return nil unless der.start_with?(ED25519_PKCS8_PREFIX)
+
+        der.byteslice(ED25519_PKCS8_PREFIX.bytesize, Ed25519::KEY_SIZE)
+      end
+
+      def decode_private_key_der(value)
+        if value.include?('BEGIN PRIVATE KEY')
+          Base64.decode64(value.gsub(/-----BEGIN PRIVATE KEY-----|-----END PRIVATE KEY-----|\s+/, ''))
+        else
+          value
+        end
+      end
+
+      def sign_with_private_key(private_key, message)
+        case private_key
+        when OpenSSL::PKey::PKey
+          private_key.sign(nil, message)
+        when Ed25519::SigningKey
+          private_key.sign(message)
+        else
+          raise ArgumentError, 'private_key must be an Ed25519 private key'
+        end
+      rescue OpenSSL::OpenSSLError, Ed25519::Error => e
+        raise ArgumentError, "private_key must be an Ed25519 private key: #{e.message}"
+      end
+
+      def seed_to_pem(seed)
+        der = ED25519_PKCS8_PREFIX + seed
+        encoded = Base64.strict_encode64(der).scan(/.{1,64}/).join("\n")
+        "-----BEGIN PRIVATE KEY-----\n#{encoded}\n-----END PRIVATE KEY-----\n"
+      end
+
+      def base64url_encode(value)
+        Base64.urlsafe_encode64(value, padding: false)
+      end
+    end
+  end
+end

data/lib/carddb/filter_builder.rb

@@ -36,9 +36,9 @@ module CardDB
     #
     # @yield Block to define filters
     # @return [Hash] The filter hash
-    def self.build(&block)
+    def self.build(&)
       builder = new
-      builder.instance_eval(&block)
+      builder.instance_eval(&)
       builder.to_filter
     end
 
@@ -62,9 +62,9 @@ module CardDB
     #
     # @yield Block to define OR conditions
     # @return [self]
-    def any(&block)
+    def any(&)
       or_builder = FilterBuilder.new
-      or_builder.instance_eval(&block)
+      or_builder.instance_eval(&)
       or_conditions = or_builder.conditions_array
       @or_groups << { '$or' => or_conditions } if or_conditions.any?
       self