carddb 0.2.1 → 0.3.0

data/lib/carddb/collection.rb

@@ -245,6 +245,16 @@ module CardDB
     def to_json(*args)
       data.to_json(*args)
     end
+
+    private
+
+    def parse_time(value)
+      return nil unless value
+
+      Time.parse(value)
+    rescue ArgumentError
+      value
+    end
   end
 
   # Wrapper for Publisher objects
@@ -436,6 +446,10 @@ module CardDB
       data['purpose']
     end
 
+    def tcgplayer_product_id_field_key
+      data['tcgplayerProductIdFieldKey']
+    end
+
     def visibility
       data['visibility']
     end
@@ -531,10 +545,11 @@ module CardDB
     #
     # @param first [Integer, nil] Maximum number of results
     # @param filter [Hash, nil] Filter conditions (alternative to block)
+    # @param include_pricing [Boolean] Include live TCGPlayer pricing when configured
     # @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, &block)
+    def records(first: nil, filter: nil, include_pricing: false, &block)
       raise Error, 'No client available to fetch records' unless client
 
       publisher_slug = publisher&.[]('slug')
@@ -549,6 +564,7 @@ module CardDB
         dataset_key: key,
         first: first,
         filter: filter,
+        include_pricing: include_pricing,
         &block
       )
     end
@@ -707,6 +723,10 @@ module CardDB
       @resolved_links ||= parse_resolved_links
     end
 
+    def pricing
+      data['pricing']
+    end
+
     def created_at
       parse_time(data['createdAt'])
     end
@@ -750,8 +770,8 @@ module CardDB
     def parse_resolved_links
       return {} unless data['resolvedLinks']
 
-      data['resolvedLinks'].each_with_object({}) do |link, hash|
-        hash[link['field']] = ResolvedLink.new(link, client: client)
+      data['resolvedLinks'].to_h do |link|
+        [link['field'], ResolvedLink.new(link, client: client)]
       end
     end
 
@@ -770,6 +790,30 @@ module CardDB
       data['id']
     end
 
+    def owner_type
+      data['ownerType']
+    end
+
+    def owner_account_id
+      data['ownerAccountId']
+    end
+
+    def owner_api_application_id
+      data['ownerApiApplicationId']
+    end
+
+    def environment
+      data['environment']
+    end
+
+    def created_by_account_id
+      data['createdByAccountId']
+    end
+
+    def created_by_api_application_id
+      data['createdByApiApplicationId']
+    end
+
     def account_id
       data['accountId']
     end
@@ -810,10 +854,54 @@ module CardDB
       data['visibility']
     end
 
+    def access_mode
+      data['accessMode']
+    end
+
+    def discoverability
+      data['discoverability']
+    end
+
+    def state
+      data['state']
+    end
+
+    def archived?
+      state == 'ARCHIVED'
+    end
+
+    def deleted?
+      state == 'DELETED'
+    end
+
+    def archived_at
+      parse_time(data['archivedAt'])
+    end
+
+    def deleted_at
+      parse_time(data['deletedAt'])
+    end
+
+    def unpublished_at
+      parse_time(data['unpublishedAt'])
+    end
+
+    def external_ref_api_application_id
+      data['externalRefApiApplicationId']
+    end
+
     def external_ref
       data['externalRef']
     end
 
+    def external_subject_ref
+      data['externalSubjectRef']
+    end
+
+    def ruleset_id
+      data['rulesetId']
+    end
+
     def source_url
       data['sourceUrl']
     end
@@ -826,6 +914,12 @@ module CardDB
       @entries ||= (data['entries'] || []).map { |entry| DeckEntry.new(entry, client: client) }
     end
 
+    def section_definitions
+      @section_definitions ||= (data['sectionDefinitions'] || []).map do |definition|
+        DeckSectionDefinition.new(definition, client: client)
+      end
+    end
+
     def latest_published_version
       @latest_published_version ||= data['latestPublishedVersion'] ? DeckVersion.new(data['latestPublishedVersion'], client: client) : nil
     end
@@ -834,6 +928,22 @@ module CardDB
       parse_time(data['publishedAt'])
     end
 
+    def draft_revision
+      data['draftRevision']
+    end
+
+    def draft_updated_at
+      parse_time(data['draftUpdatedAt'])
+    end
+
+    def draft_updated_by_account_id
+      data['draftUpdatedByAccountId']
+    end
+
+    def draft_updated_by_api_application_id
+      data['draftUpdatedByApiApplicationId']
+    end
+
     def has_unpublished_changes?
       !!data['hasUnpublishedChanges']
     end
@@ -919,6 +1029,40 @@ module CardDB
       data['computedDiff'] || {}
     end
 
+    def ruleset_id
+      data['rulesetId']
+    end
+
+    def ruleset_version_id
+      data['rulesetVersionId']
+    end
+
+    def card_dataset_id
+      data['cardDatasetId']
+    end
+
+    def card_dataset_version_id
+      data['cardDatasetVersionId']
+    end
+
+    def validated_at
+      parse_time(data['validatedAt'])
+    end
+
+    def validation_summary
+      data['validationSummary'] || {}
+    end
+
+    def validated_against
+      @validated_against ||= data['validatedAgainst'] ? DeckValidatedAgainst.new(data['validatedAgainst'], client: client) : nil
+    end
+
+    def section_definitions
+      @section_definitions ||= (data['sectionDefinitions'] || []).map do |definition|
+        DeckSectionDefinition.new(definition, client: client)
+      end
+    end
+
     def published_by_account_id
       data['publishedByAccountId']
     end
@@ -983,6 +1127,49 @@ module CardDB
     end
   end
 
+  class DeckOwnershipTransferPayload < Resource
+    def deck
+      @deck ||= Deck.new(data['deck'], client: client)
+    end
+
+    def retained_app_access? = !!data['retainedAppAccess']
+  end
+
+  class DeckCopyPayload < DeckOwnershipTransferPayload
+    def copied_from_deck_id = data['copiedFromDeckId']
+  end
+
+  class DeckAccessApplication < Resource
+    def id = data['id']
+    def name = data['name']
+    def description = data['description']
+    def revoked_at = parse_time(data['revokedAt'])
+  end
+
+  class DeckAPIApplicationAccess < Resource
+    def id = data['id']
+    def deck_id = data['deckId']
+
+    def deck
+      @deck ||= data['deck'] ? Deck.new(data['deck'], client: client) : nil
+    end
+
+    def api_application_id = data['apiApplicationId']
+
+    def api_application
+      @api_application ||= data['apiApplication'] ? DeckAccessApplication.new(data['apiApplication'], client: client) : nil
+    end
+
+    def role = data['role']
+    def grant_source = data['grantSource']
+    def external_ref = data['externalRef']
+    def created_by_account_id = data['createdByAccountId']
+    def created_by_api_application_id = data['createdByApiApplicationId']
+    def revoked_at = parse_time(data['revokedAt'])
+    def created_at = parse_time(data['createdAt'])
+    def updated_at = parse_time(data['updatedAt'])
+  end
+
   # Wrapper for deck preview token metadata
   class DeckPreviewToken < Resource
     def id
@@ -1039,6 +1226,329 @@ module CardDB
     end
   end
 
+  class DeckEmbedToken < Resource
+    def id = data['id']
+    def deck_id = data['deckId']
+    def api_application_id = data['apiApplicationId']
+    def label = data['label']
+    def read_mode = data['readMode']
+    def allowed_origins = data['allowedOrigins'] || []
+    def external_subject = data['externalSubject']
+    def expires_at = parse_time(data['expiresAt'])
+    def revoked_at = parse_time(data['revokedAt'])
+    def last_used_at = parse_time(data['lastUsedAt'])
+    def created_at = parse_time(data['createdAt'])
+    def updated_at = parse_time(data['updatedAt'])
+  end
+
+  class DeckEmbedTokenCreatePayload < Resource
+    def token = data['token']
+
+    def embed_token
+      @embed_token ||= data['embedToken'] ? DeckEmbedToken.new(data['embedToken'], client: client) : nil
+    end
+  end
+
+  class DeckAccessTokenIssuer < Resource
+    def id = data['id']
+    def deck_id = data['deckId']
+    def api_application_id = data['apiApplicationId']
+    def label = data['label']
+    def read_modes = data['readModes'] || []
+    def max_token_lifetime_seconds = data['maxTokenLifetimeSeconds']
+    def direct_signing_alg = data['directSigningAlg']
+    def direct_signing_key_id = data['directSigningKeyId']
+    def direct_signing_public_key = data['directSigningPublicKey']
+    def direct_signing_key_revoked_at = parse_time(data['directSigningKeyRevokedAt'])
+    def revoked_at = parse_time(data['revokedAt'])
+    def created_at = parse_time(data['createdAt'])
+    def updated_at = parse_time(data['updatedAt'])
+  end
+
+  class DeckAccessToken < Resource
+    def id = data['id']
+    def deck_id = data['deckId']
+    def api_application_id = data['apiApplicationId']
+    def issuer_id = data['issuerId']
+    def read_mode = data['readMode']
+    def external_subject = data['externalSubject']
+    def expires_at = parse_time(data['expiresAt'])
+    def revoked_at = parse_time(data['revokedAt'])
+    def last_used_at = parse_time(data['lastUsedAt'])
+    def created_at = parse_time(data['createdAt'])
+    def updated_at = parse_time(data['updatedAt'])
+  end
+
+  class DeckAccessTokenExchangePayload < Resource
+    def token = data['token']
+
+    def access_token
+      @access_token ||= data['accessToken'] ? DeckAccessToken.new(data['accessToken'], client: client) : nil
+    end
+  end
+
+  class DeckSectionDefinition < Resource
+    def key = data['key']
+    def label = data['label']
+    def description = data['description']
+    def order = data['order']
+    def default? = !!data['default']
+    def aliases = data['aliases'] || []
+    def min_cards = data['minCards']
+    def max_cards = data['maxCards']
+    def excluded_from_deck_size? = !!data['excludedFromDeckSize']
+    def legal_card_types = data['legalCardTypes'] || []
+    def metadata = data['metadata'] || {}
+  end
+
+  class DeckValidatedAgainst < Resource
+    def ruleset_id = data['rulesetId']
+    def ruleset_version_id = data['rulesetVersionId']
+    def ruleset_version_label = data['rulesetVersionLabel']
+    def card_dataset_id = data['cardDatasetId']
+    def card_dataset_version_id = data['cardDatasetVersionId']
+    def validated_at = parse_time(data['validatedAt'])
+    def validation_result_summary = data['validationResultSummary'] || {}
+  end
+
+  class DeckValidationIssue < Resource
+    def code = data['code']
+    def severity = data['severity']
+    def message = data['message']
+    def entry_ids = data['entryIds'] || []
+    def section = data['section']
+    def dataset_id = data['datasetId']
+    def identifier = data['identifier']
+    def metadata = data['metadata'] || {}
+  end
+
+  class DeckValidationAffectedEntry < Resource
+    def entry_id = data['entryId']
+    def dataset_id = data['datasetId']
+    def record_id = data['recordId']
+    def identifier = data['identifier']
+    def section = data['section']
+    def quantity = data['quantity']
+  end
+
+  class DeckValidation < Resource
+    def deck_id = data['deckId']
+    def valid? = !!data['valid']
+    def checked_at = parse_time(data['checkedAt'])
+
+    def blockers
+      @blockers ||= (data['blockers'] || []).map { |issue| DeckValidationIssue.new(issue, client: client) }
+    end
+
+    def warnings
+      @warnings ||= (data['warnings'] || []).map { |issue| DeckValidationIssue.new(issue, client: client) }
+    end
+
+    def affected_entries
+      @affected_entries ||= (data['affectedEntries'] || []).map do |entry|
+        DeckValidationAffectedEntry.new(entry, client: client)
+      end
+    end
+
+    def validated_against
+      @validated_against ||= DeckValidatedAgainst.new(data['validatedAgainst'], client: client)
+    end
+  end
+
+  class DeckDiff < Resource
+    def deck_id = data['deckId']
+    def from_version_id = data['fromVersionId']
+    def to_version_id = data['toVersionId']
+    def to_draft_revision = data['toDraftRevision']
+    def changes? = !!data['hasChanges']
+    def diff = data['diff'] || {}
+  end
+
+  class DeckPublishPayload < Resource
+    def deck
+      @deck ||= Deck.new(data['deck'], client: client)
+    end
+
+    def version
+      @version ||= data['version'] ? DeckVersion.new(data['version'], client: client) : nil
+    end
+
+    def validation
+      @validation ||= DeckValidation.new(data['validation'], client: client)
+    end
+
+    def blockers
+      @blockers ||= (data['blockers'] || []).map { |issue| DeckValidationIssue.new(issue, client: client) }
+    end
+
+    def warnings
+      @warnings ||= (data['warnings'] || []).map { |issue| DeckValidationIssue.new(issue, client: client) }
+    end
+  end
+
+  class DeckEntryMutationPayload < Resource
+    def deck
+      @deck ||= Deck.new(data['deck'], client: client)
+    end
+
+    def entry
+      @entry ||= data['entry'] ? DeckEntry.new(data['entry'], client: client) : nil
+    end
+  end
+
+  class DeckEntryReorderPayload < Resource
+    def deck
+      @deck ||= Deck.new(data['deck'], client: client)
+    end
+
+    def entries
+      @entries ||= (data['entries'] || []).map { |entry| DeckEntry.new(entry, client: client) }
+    end
+  end
+
+  class DeckEntriesReplacePayload < DeckEntryReorderPayload; end
+
+  class DeckUpsertByExternalRefPayload < Resource
+    def deck
+      @deck ||= Deck.new(data['deck'], client: client)
+    end
+
+    def created? = !!data['created']
+    def idempotent_replay? = !!data['idempotentReplay']
+  end
+
+  class DeckImportEntry < Resource
+    def line_number = data['lineNumber']
+    def raw = data['raw']
+    def dataset_key = data['datasetKey']
+    def dataset_id = data['datasetId']
+    def record_id = data['recordId']
+    def identifier = data['identifier']
+    def quantity = data['quantity']
+    def section = data['section']
+    def sort_order = data['sortOrder']
+    def display = data['display'] || {}
+
+    def record
+      @record ||= data['record'] ? Record.new(data['record'], client: client) : nil
+    end
+  end
+
+  class DeckImportIssue < Resource
+    def line_number = data['lineNumber']
+    def raw = data['raw']
+    def code = data['code']
+    def message = data['message']
+  end
+
+  class DeckImportUnmatchedEntry < DeckImportIssue
+    def dataset_key = data['datasetKey']
+    def identifier = data['identifier']
+    def quantity = data['quantity']
+    def section = data['section']
+  end
+
+  class DeckImportCandidate < Resource
+    def record_id = data['recordId']
+    def identifier = data['identifier']
+    def display = data['display'] || {}
+  end
+
+  class DeckImportAmbiguousEntry < Resource
+    def line_number = data['lineNumber']
+    def raw = data['raw']
+    def dataset_key = data['datasetKey']
+    def identifier = data['identifier']
+    def quantity = data['quantity']
+    def section = data['section']
+
+    def candidates
+      @candidates ||= (data['candidates'] || []).map { |candidate| DeckImportCandidate.new(candidate, client: client) }
+    end
+  end
+
+  class DeckImportFormatDefinition < Resource
+    def id = data['id']
+    def game_id = data['gameId']
+    def key = data['key']
+    def name = data['name']
+    def description = data['description']
+    def enabled? = !!data['enabled']
+    def priority = data['priority']
+    def dataset_key = data['datasetKey']
+    def config = data['config'] || {}
+    def archived_at = parse_time(data['archivedAt'])
+    def archived? = !!data['isArchived']
+    def created_at = parse_time(data['createdAt'])
+    def updated_at = parse_time(data['updatedAt'])
+  end
+
+  class DeckImportFormatDetection < Resource
+    def format_id = data['formatId']
+    def key = data['key']
+    def name = data['name']
+    def confidence = data['confidence']
+    def reason = data['reason']
+  end
+
+  class DeckHydrateEntriesPayload < Resource
+    def entries
+      @entries ||= (data['entries'] || []).map { |entry| DeckImportEntry.new(entry, client: client) }
+    end
+
+    def unmatched
+      @unmatched ||= (data['unmatched'] || []).map { |entry| DeckImportUnmatchedEntry.new(entry, client: client) }
+    end
+
+    def ambiguous
+      @ambiguous ||= (data['ambiguous'] || []).map { |entry| DeckImportAmbiguousEntry.new(entry, client: client) }
+    end
+  end
+
+  class DeckImportFormatTestPayload < DeckHydrateEntriesPayload
+    def detection
+      @detection ||= data['detection'] ? DeckImportFormatDetection.new(data['detection'], client: client) : nil
+    end
+
+    def parse_errors
+      @parse_errors ||= (data['parseErrors'] || []).map { |issue| DeckImportIssue.new(issue, client: client) }
+    end
+  end
+
+  class DeckImportPayload < DeckHydrateEntriesPayload
+    def deck
+      @deck ||= data['deck'] ? Deck.new(data['deck'], client: client) : nil
+    end
+
+    def applied? = !!data['applied']
+    def dry_run? = !!data['dryRun']
+    def replace? = !!data['replace']
+    def format = data['format']
+
+    def import_format
+      @import_format ||= data['importFormat'] ? DeckImportFormatDefinition.new(data['importFormat'], client: client) : nil
+    end
+
+    def detection
+      @detection ||= data['detection'] ? DeckImportFormatDetection.new(data['detection'], client: client) : nil
+    end
+
+    def parse_errors
+      @parse_errors ||= (data['parseErrors'] || []).map { |issue| DeckImportIssue.new(issue, client: client) }
+    end
+
+    def validation
+      @validation ||= data['validation'] ? DeckValidation.new(data['validation'], client: client) : nil
+    end
+  end
+
+  class DeckExportPayload < Resource
+    def deck_id = data['deckId']
+    def format = data['format']
+    def text = data['text']
+    def entry_count = data['entryCount']
+  end
+
   # Wrapper for hosted DeckEntry objects
   class DeckEntry < Resource
     def id
@@ -1073,6 +1583,10 @@ module CardDB
       data['annotations'] || {}
     end
 
+    def display
+      data['display'] || {}
+    end
+
     def record
       @record ||= data['record'] ? Record.new(data['record'], client: client) : nil
     end

data/lib/carddb/configuration.rb

@@ -41,9 +41,21 @@ module CardDB
     # Default retry settings
     DEFAULT_MAX_RETRIES = 3
 
-    # @return [String, nil] API key for authentication
+    # @return [String, nil] Legacy API key for authentication
     attr_accessor :api_key
 
+    # @return [String, nil] Browser-safe publishable API key for public reads
+    attr_accessor :publishable_key
+
+    # @return [String, nil] Server-side secret API key for trusted workflows
+    attr_accessor :secret_key
+
+    # @return [String, nil] OAuth bearer token for user-authorized requests
+    attr_accessor :access_token
+
+    # @return [String, nil] Client environment hint (`TEST` or `LIVE`)
+    attr_accessor :environment
+
     # @return [String] GraphQL endpoint URL
     attr_accessor :endpoint
 
@@ -93,6 +105,10 @@ module CardDB
       @timeout = DEFAULT_TIMEOUT
       @open_timeout = DEFAULT_OPEN_TIMEOUT
       @api_key = nil
+      @publishable_key = nil
+      @secret_key = nil
+      @access_token = nil
+      @environment = nil
       @default_publisher = nil
       @default_game = nil
       @allowed_publishers = nil
@@ -154,6 +170,16 @@ module CardDB
       validate_game!(publisher_slug, game_key) if publisher_slug && game_key
     end
 
+    def effective_api_key
+      api_key || publishable_key || secret_key
+    end
+
+    def require_secret_credential!(operation)
+      return if !access_token && (api_key || (secret_key && !publishable_key))
+
+      raise RestrictedError, "#{operation} requires a server-side secret_key or legacy api_key credential"
+    end
+
     # Resolves the publisher slug, using the default if not provided.
     #
     # @param publisher_slug [String, nil] The provided publisher slug

data/lib/carddb/connection.rb

@@ -71,8 +71,11 @@ module CardDB
         f.headers['Accept'] = 'application/json'
         f.headers['User-Agent'] = "CardDB-SDK/ruby/#{CardDB::VERSION} (ruby/#{RUBY_VERSION})"
 
-        # Set API key header if configured
-        f.headers['X-API-Key'] = config.api_key if config.api_key
+        if config.access_token
+          f.headers['Authorization'] = "Bearer #{config.access_token}"
+        elsif config.effective_api_key
+          f.headers['X-API-Key'] = config.effective_api_key
+        end
 
         f.options.timeout = config.timeout
         f.options.open_timeout = config.open_timeout