harkness 1.0.0

data/lib/harkness/models/base/data_wrapper.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Harkness
+  module Base
+    # The top level wrapper of a response from the API.
+    class DataWrapper < Shale::Mapper
+      # @!attribute [r] code
+      #   @return [Integer] the HTTP status code of the returned result.
+      attribute :code, Shale::Type::Integer
+      # @!attribute [r] status
+      #   @return [String] a string description of the call status.
+      attribute :status, Shale::Type::String
+      # @!attribute [r] copyright
+      #   @return [String] the copyright notice for the returned result.
+      attribute :copyright, Shale::Type::String
+      # @!attribute [r] attributionText
+      #   @return [String] the attribution notice for this result.
+      #     Please display either this notice or the contents of the attributionHTML field on all
+      #     screens which contain data from the Marvel Comics API.
+      attribute :attributionText, Shale::Type::String
+      # @!attribute [r] attributionHTML
+      #   @return [String] an HTML representation of the attribution notice for this result.
+      #     Please display either this notice or the contents of the attributionText field on all
+      #     screens which contain data from the Marvel Comics API.
+      attribute :attributionHTML, Shale::Type::String
+      # @!attribute [r] data
+      #   @return [Harkness::Base::DataContainer] the results returned by the call.
+      attribute :data, Harkness::Base::DataContainer
+      # @!attribute [r] etag
+      #   @return [String] a digest value of the content returned by the call.
+      attribute :etag, Shale::Type::String
+    end
+  end
+end

data/lib/harkness/models/base/summary.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Harkness
+  module Base
+    # Base class for the "summary" objects in an API response. These summary objects are
+    #   linked objects to the main API response. For example, when retrieving a Character,
+    #   one of the summary objects is a Series.
+    class Summary < Shale::Mapper
+      # @!attribute [r] resourceURI
+      #   @return [String] the path to the individual resource.
+      attribute :resourceURI, Shale::Type::String
+      # @!attribute [r] name
+      #   @return [String] the canonical name of the resource.
+      attribute :name, Shale::Type::String
+    end
+  end
+end

data/lib/harkness/models/character.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Harkness
+  # An individual character.
+  class Character < Shale::Mapper
+    # @!attribute [r] id
+    #   @return [Integer] the unique ID of the character resource.
+    attribute :id, Shale::Type::Integer
+    # @!attribute [r] name
+    #   @return [String] the name of the character.
+    attribute :name, Shale::Type::String
+    # @!attribute [r] description
+    #   @return [String] a short bio or description of the character
+    attribute :description, Shale::Type::String
+    # @!attribute [r] modified
+    #   @return [String] the date the resource was most recently modified.
+    attribute :modified, Shale::Type::String
+    # @!attribute [r] resourceURI
+    #   @return [String] the canonical URL identifier for this resource.
+    attribute :resourceURI, Shale::Type::String
+    # @!attribute [r] urls
+    #   @return [Array<Harkness::URL>] a set of public web site URLs for the resource.
+    attribute :urls, Harkness::URL, collection: true
+    # @!attribute [r] thumbnail
+    #   @return [Harkness::Image] the representative image for this character.
+    attribute :thumbnail, Harkness::Image
+    # @!attribute [r] comics
+    #   @return [Harkness::ComicList] a resource list containing comics which feature this character.
+    attribute :comics, Harkness::ComicList
+    # @!attribute [r] stories
+    #   @return [Harkness::StoryList] a resource list of stories in which this character appears.
+    attribute :stories, Harkness::StoryList
+    # @!attribute [r] events
+    #   @return [Harkness::EventList] a resource list of events in which this character appears.
+    attribute :events, Harkness::EventList
+    # @!attribute [r] series
+    #   @return [Harkness::SeriesList] a resource list of series in which this character appears.
+    attribute :series, Harkness::SeriesList
+  end
+
+  # Container class that holds pagination information and results
+  class CharacterDataContainer < Harkness::Base::DataContainer
+    # @!attribute [r] results
+    #   @return [Array<Harkness::Character>] the list of characters returned by the call.
+    attribute :results, Harkness::Character, collection: true
+  end
+
+  # The top level wrapper of a response from the API.
+  class CharacterDataWrapper < Harkness::Base::DataWrapper
+    # @!attribute [r] data
+    #   @return [CharacterDataContainer] the results returned by the call.
+    attribute :data, Harkness::CharacterDataContainer
+  end
+end

data/lib/harkness/models/character_list.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Harkness
+  # The summary of a character.
+  class CharacterSummary < Harkness::Base::Summary
+    # @!attribute [r] role
+    #   @return [String] the role of the creator in the parent entity.
+    attribute :role, Shale::Type::String
+  end
+
+  # A list of characters.
+  class CharacterList < Shale::Mapper
+    # @!attribute [r] available
+    #   @return [Integer] the number of total available characters in this list.
+    #     Will always be greater than or equal to the "returned" value.
+    attribute :available, Shale::Type::Integer
+    # @!attribute [r] returned
+    #   @return [Integer] the number of characters returned in this collection (up to 20).
+    attribute :returned, Shale::Type::Integer
+    # @!attribute [r] collectionURI
+    #   @return [String] the path to the full list of characters in this collection.
+    attribute :collectionURI, Shale::Type::String
+    # @!attribute [r] offset
+    #   @return [Array<Harkness::CharacterSummary>] the list of returned characters in this collection.
+    attribute :items, Harkness::CharacterSummary, collection: true
+  end
+end

data/lib/harkness/models/comic.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Harkness
+  class ComicDate < Shale::Mapper
+    attribute :type, Shale::Type::String
+    attribute :date, Shale::Type::String
+  end
+
+  class ComicPrice < Shale::Mapper
+    attribute :type, Shale::Type::String
+    attribute :price, Shale::Type::Float
+  end
+
+  class Comic < Shale::Mapper
+    attribute :id, Shale::Type::Integer
+    attribute :digitalId, Shale::Type::Integer
+    attribute :title, Shale::Type::String
+    attribute :issueNumber, Shale::Type::Integer
+    attribute :variantDescription, Shale::Type::String
+    attribute :description, Shale::Type::String
+    attribute :modified, Shale::Type::String
+    attribute :isbn, Shale::Type::String
+    attribute :upc, Shale::Type::String
+    attribute :diamondCode, Shale::Type::String
+    attribute :ean, Shale::Type::String
+    attribute :issn, Shale::Type::String
+    attribute :format, Shale::Type::String
+    attribute :pageCount, Shale::Type::Integer
+    attribute :textObjects, Harkness::TextObject, collection: true
+    attribute :resourceURI, Shale::Type::String
+    attribute :urls, Harkness::URL, collection: true
+    attribute :series, Harkness::SeriesSummary
+    attribute :variants, Harkness::ComicSummary, collection: true
+    attribute :collections, Harkness::ComicSummary, collection: true
+    attribute :collectedIssues, Harkness::ComicSummary, collection: true
+    attribute :dates, Harkness::ComicDate, collection: true
+    attribute :prices, Harkness::ComicPrice, collection: true
+    attribute :thumbnail, Harkness::Image
+    attribute :images, Harkness::Image, collection: true
+    attribute :creators, Harkness::CreatorList
+    attribute :characters, Harkness::CharacterList
+    attribute :stories, Harkness::StoryList
+    attribute :events, Harkness::EventList
+  end
+
+  class ComicDataContainer < Harkness::Base::DataContainer
+    attribute :results, Harkness::Comic, collection: true
+  end
+
+  class ComicDataWrapper < Harkness::Base::DataWrapper
+    attribute :data, Harkness::ComicDataContainer
+  end
+end

data/lib/harkness/models/comic_list.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Harkness
+  class ComicSummary < Harkness::Base::Summary
+  end
+
+  class ComicList < Shale::Mapper
+    attribute :available, Shale::Type::Integer
+    attribute :collectionURI, Shale::Type::String
+    attribute :items, Harkness::ComicSummary, collection: true
+  end
+end

data/lib/harkness/models/creator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Harkness
+  class Creator < Shale::Mapper
+    attribute :id, Shale::Type::Integer
+    attribute :firstName, Shale::Type::String
+    attribute :middleName, Shale::Type::String
+    attribute :lastName, Shale::Type::String
+    attribute :suffix, Shale::Type::String
+    attribute :fullName, Shale::Type::String
+    attribute :modified, Shale::Type::String
+    attribute :resourceURI, Shale::Type::String
+    attribute :urls, Harkness::URL, collection: true
+    attribute :thumbnail, Harkness::Image
+    attribute :series, Harkness::SeriesList
+    attribute :stories, Harkness::StoryList
+    attribute :comics, Harkness::ComicList
+    attribute :events, Harkness::EventList
+  end
+
+  class CreatorDataContainer < Harkness::Base::DataContainer
+    attribute :results, Harkness::Creator, collection: true
+  end
+
+  class CreatorDataWrapper < Harkness::Base::DataWrapper
+    attribute :data, Harkness::CreatorDataContainer
+  end
+end

data/lib/harkness/models/creator_list.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Harkness
+  class CreatorSummary < Harkness::Base::Summary
+    attribute :role, Shale::Type::String
+  end
+
+  class CreatorList < Shale::Mapper
+    attribute :available, Shale::Type::Integer
+    attribute :returned, Shale::Type::Integer
+    attribute :collectionURI, Shale::Type::String
+    attribute :items, Harkness::CreatorSummary, collection: true
+  end
+end

data/lib/harkness/models/event.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Harkness
+  class Event < Shale::Mapper
+    attribute :id, Shale::Type::Integer
+    attribute :title, Shale::Type::String
+    attribute :description, Shale::Type::String
+    attribute :resourceURI, Shale::Type::String
+    attribute :urls, Harkness::URL, collection: true
+    attribute :modified, Shale::Type::String
+    attribute :start, Shale::Type::String
+    attribute :end, Shale::Type::String
+    attribute :thumbnail, Harkness::Image
+    attribute :comics, Harkness::ComicList
+    attribute :stories, Harkness::StoryList
+    attribute :series, Harkness::SeriesList
+    attribute :characters, Harkness::CharacterList
+    attribute :creators, Harkness::CreatorList
+    attribute :next, Harkness::EventSummary
+    attribute :previous, Harkness::EventSummary
+  end
+
+  class EventDataContainer < Harkness::Base::DataContainer
+    attribute :results, Harkness::Event, collection: true
+  end
+
+  class EventDataWrapper < Harkness::Base::DataWrapper
+    attribute :data, Harkness::EventDataContainer
+  end
+end

data/lib/harkness/models/event_list.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Harkness
+  class EventSummary < Harkness::Base::Summary
+  end
+
+  class EventList < Shale::Mapper
+    attribute :available, Shale::Type::Integer
+    attribute :collectionURI, Shale::Type::String
+    attribute :items, Harkness::EventSummary, collection: true
+  end
+end

data/lib/harkness/models/image.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Harkness
+  # An image.
+  class Image < Shale::Mapper
+    attribute :path, Shale::Type::String
+    attribute :extension, Shale::Type::String
+  end
+end

data/lib/harkness/models/series.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Harkness
+  class Series < Shale::Mapper
+    attribute :id, Shale::Type::Integer
+    attribute :title, Shale::Type::String
+    attribute :description, Shale::Type::String
+    attribute :resourceURI, Shale::Type::String
+    attribute :urls, Harkness::URL, collection: true
+
+    attribute :startYear, Shale::Type::Integer
+    attribute :endYear, Shale::Type::Integer
+    attribute :rating, Shale::Type::String
+    attribute :modified, Shale::Type::String
+    attribute :thumbnail, Harkness::Image
+    attribute :comics, Harkness::ComicList
+    attribute :stories, Harkness::StoryList
+    attribute :events, Harkness::EventList
+    attribute :characters, Harkness::CharacterList
+    attribute :creators, Harkness::CreatorList
+    attribute :next, Harkness::SeriesSummary
+    attribute :previous, Harkness::SeriesSummary
+  end
+
+  class SeriesDataContainer < Harkness::Base::DataContainer
+    attribute :results, Harkness::Series, collection: true
+  end
+
+  class SeriesDataWrapper < Harkness::Base::DataWrapper
+    attribute :data, Harkness::SeriesDataContainer
+  end
+end

data/lib/harkness/models/series_list.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Harkness
+  class SeriesSummary < Harkness::Base::Summary
+  end
+
+  class SeriesList < Shale::Mapper
+    attribute :available, Shale::Type::Integer
+    attribute :collectionURI, Shale::Type::String
+    attribute :items, Harkness::SeriesSummary, collection: true
+  end
+end

data/lib/harkness/models/story.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Harkness
+  class Story < Shale::Mapper
+    attribute :id, Shale::Type::Integer
+    attribute :title, Shale::Type::String
+    attribute :description, Shale::Type::String
+    attribute :resourceURI, Shale::Type::String
+    attribute :type, Shale::Type::String
+    attribute :modified, Shale::Type::String
+    attribute :thumbnail, Harkness::Image
+    attribute :comics, Harkness::ComicList
+    attribute :series, Harkness::SeriesList
+    attribute :events, Harkness::EventList
+    attribute :characters, Harkness::CharacterList
+    attribute :originalIssue, Harkness::ComicSummary
+  end
+
+  class StoryDataContainer < Harkness::Base::DataContainer
+    attribute :results, Harkness::Story, collection: true
+  end
+
+  class StoryDataWrapper < Harkness::Base::DataWrapper
+    attribute :data, Harkness::StoryDataContainer
+  end
+end

data/lib/harkness/models/story_list.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Harkness
+  class StorySummary < Harkness::Base::Summary
+    attribute :type, Shale::Type::String
+  end
+
+  class StoryList < Shale::Mapper
+    attribute :available, Shale::Type::Integer
+    attribute :collectionURI, Shale::Type::String
+    attribute :items, Harkness::StorySummary, collection: true
+  end
+end

data/lib/harkness/models/text_object.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Harkness
+  # A text objct
+  class TextObject < Shale::Mapper
+    attribute :type, Shale::Type::String
+    attribute :language, Shale::Type::String
+    attribute :text, Shale::Type::String
+  end
+end

data/lib/harkness/models/url.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Harkness
+  # A URL.
+  class URL < Shale::Mapper
+    attribute :type, Shale::Type::String
+    attribute :url, Shale::Type::String
+  end
+end

data/lib/harkness/resource.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Harkness
+  class Resource
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    private
+
+    def get_request(url, params: {}, headers: {})
+      handle_response client.connection.get(url, authentication_params.merge(params), headers)
+    end
+
+    def authentication_params
+      timestamp = Time.now.to_i
+      {
+        ts: timestamp,
+        apikey: @client.public_key,
+        hash: Digest::MD5.hexdigest(timestamp.to_s + @client.private_key + @client.public_key)
+      }
+    end
+
+    def handle_response(response)
+      error_klass = Harkness::Error::STATUS_MAPPINGS[response.status]
+      message = JSON.parse(response.body)["status"] || "API request failed with an unknown error."
+      raise error_klass, message if error_klass
+
+      response
+    end
+  end
+end

data/lib/harkness/resources/character.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Harkness
+  # The character resource.
+  class CharacterResource < Resource
+    # Get a list of characters.
+    # @param params [Hash] the params to pass to the API request.
+    #   See the [characters documentation from Marvel](https://developer.marvel.com/docs#!/public/getCreatorCollection_get_0)
+    #   for valid options.
+    # @return [Harkness::CharacterDataWrapper] the top level wrapper around the character API response.
+    # @example
+    #   client.characters.list
+    #   client.characters.list(nameStartsWith: "Ant-", limit: 10, orderBy: "-modified")
+    def list(**params)
+      CharacterDataWrapper.from_json(get_request("characters", params: params).body)
+    end
+
+    # Get a single character.
+    # @param character_id [Integer] the ID of the character.
+    # @return [Harkness::CharacterDataWrapper] the top level wrapper around the character API response.
+    # @example
+    #   client.characters.retrieve(character_id: 1234)
+    def retrieve(character_id:)
+      CharacterDataWrapper.from_json(get_request("characters/#{character_id}").body)
+    end
+
+    # Get a list of comics for a particular character.
+    # @param character_id [Integer] the ID of the character.
+    # @return [Harkness::ComicDataWrapper] the top level wrapper around the comic API response.
+    # @example
+    #   client.characters.comics(character_id: 1234)
+    def comics(character_id:)
+      ComicDataWrapper.from_json(get_request("characters/#{character_id}/comics").body)
+    end
+
+    # Get a list of events for a particular character.
+    # @param character_id [Integer] the ID of the character.
+    # @return [Harkness::EventDataWrapper] the top level wrapper around the event API response.
+    # @example
+    #   client.characters.events(character_id: 1234)
+    def events(character_id:)
+      EventDataWrapper.from_json(get_request("characters/#{character_id}/events").body)
+    end
+
+    # Get a list of series for a particular character.
+    # @param character_id [Integer] the ID of the character.
+    # @return [Harkness::SeriesDataWrapper] the top level wrapper around the series API response.
+    # @example
+    #   client.characters.series(character_id: 1234)
+    def series(character_id:)
+      SeriesDataWrapper.from_json(get_request("characters/#{character_id}/series").body)
+    end
+
+    # Get a list of stories for a particular character.
+    # @param character_id [Integer] the ID of the character.
+    # @return [Harkness::StoryDataWrapper] the top level wrapper around the story API response.
+    # @example
+    #   client.stories.characters(character_id: 1234)
+    def stories(character_id:)
+      StoryDataWrapper.from_json(get_request("characters/#{character_id}/stories").body)
+    end
+  end
+end

data/lib/harkness/resources/comic.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Harkness
+  # The comic resource.
+  class ComicResource < Resource
+    # Get a list of comics.
+    # @param params [Hash] the params to pass to the API request.
+    #   See the [comics documentation from Marvel](https://developer.marvel.com/docs#!/public/getComicsCollection_get_6)
+    #   for valid options.
+    # @return [Harkness::ComicDataWrapper] the top level wrapper around the comic API response.
+    # @example
+    #   client.comics.list
+    #   client.comics.list(titleStartsWith: "Spider", limit: 10, orderBy: "issueNumber")
+    def list(**params)
+      ComicDataWrapper.from_json(get_request("comics", params: params).body)
+    end
+
+    # Get a single comic.
+    # @param comic_id [Integer] the ID of the comic.
+    # @return [Harkness::ComicDataWrapper] the top level wrapper around the comic API response.
+    # @example
+    #   client.comics.retrieve(comic_id: 1234)
+    def retrieve(comic_id:)
+      ComicDataWrapper.from_json(get_request("comics/#{comic_id}").body)
+    end
+
+    # Get a list of characters for a particular comic.
+    # @param comic_id [Integer] the ID of the comic.
+    # @return [Harkness::CharacterDataWrapper] the top level wrapper around the character API response.
+    # @example
+    #   client.comics.characters(comic_id: 1234)
+    def characters(comic_id:)
+      CharacterDataWrapper.from_json(get_request("comics/#{comic_id}/characters").body)
+    end
+
+    # Get a list of creators for a particular comic.
+    # @param comic_id [Integer] the ID of the comic.
+    # @return [Harkness::CreatorDataWrapper] the top level wrapper around the creator API response.
+    # @example
+    #   client.comics.creators(comic_id: 1234)
+    def creators(comic_id:)
+      CreatorDataWrapper.from_json(get_request("comics/#{comic_id}/creators").body)
+    end
+
+    # Get a list of events for a particular comic.
+    # @param comic_id [Integer] the ID of the comic.
+    # @return [Harkness::EventDataWrapper] the top level wrapper around the event API response.
+    # @example
+    #   client.comics.events(comic_id: 1234)
+    def events(comic_id:)
+      EventDataWrapper.from_json(get_request("comics/#{comic_id}/events").body)
+    end
+
+    # Get a list of stories for a particular comic.
+    # @param comic_id [Integer] the ID of the comic.
+    # @return [Harkness::StoryDataWrapper] the top level wrapper around the story API response.
+    # @example
+    #   client.comics.stories(comic_id: 1234)
+    def stories(comic_id:)
+      StoryDataWrapper.from_json(get_request("comics/#{comic_id}/stories").body)
+    end
+  end
+end

data/lib/harkness/resources/creator.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Harkness
+  # The creator resource.
+  class CreatorResource < Resource
+    # Get a list of creators.
+    # @param params [Hash] the params to pass to the API request.
+    #   See the [creators documentation from Marvel](https://developer.marvel.com/docs#!/public/getCreatorCollection_get_12)
+    #   for valid options.
+    # @return [Harkness::CreatorDataWrapper] the top level wrapper around the creator API response.
+    # @example
+    #   client.creators.list
+    #   client.creators.list(firstNameStartsWith: "Ben", limit: 10, orderBy: "lastName")
+    def list(**params)
+      CreatorDataWrapper.from_json(get_request("creators", params: params).body)
+    end
+
+    # Get a single creator.
+    # @param creator_id [Integer] the ID of the creator.
+    # @return [Harkness::CreatorDataWrapper] the top level wrapper around the creator API response.
+    # @example
+    #   client.creators.retrieve(creator_id: 1234)
+    def retrieve(creator_id:)
+      CreatorDataWrapper.from_json(get_request("creators/#{creator_id}").body)
+    end
+
+    # Get a list of comics for a particular creator.
+    # @param creator_id [Integer] the ID of the creator.
+    # @return [Harkness::ComicDataWrapper] the top level wrapper around the comic API response.
+    # @example
+    #   client.creators.comics(creator_id: 1234)
+    def comics(creator_id:)
+      ComicDataWrapper.from_json(get_request("creators/#{creator_id}/comics").body)
+    end
+
+    # Get a list of events for a particular creator.
+    # @param creator_id [Integer] the ID of the creator.
+    # @return [Harkness::EventDataWrapper] the top level wrapper around the event API response.
+    # @example
+    #   client.creators.events(creator_id: 1234)
+    def events(creator_id:)
+      EventDataWrapper.from_json(get_request("creators/#{creator_id}/events").body)
+    end
+
+    # Get a list of series for a particular creator.
+    # @param creator_id [Integer] the ID of the creator.
+    # @return [Harkness::SeriesDataWrapper] the top level wrapper around the series API response.
+    # @example
+    #   client.creators.series(creator_id: 1234)
+    def series(creator_id:)
+      SeriesDataWrapper.from_json(get_request("creators/#{creator_id}/series").body)
+    end
+
+    # Get a list of stories for a particular creator.
+    # @param creator_id [Integer] the ID of the creator.
+    # @return [Harkness::StoryDataWrapper] the top level wrapper around the story API response.
+    # @example
+    #   client.creators.stories(creator_id: 1234)
+    def stories(creator_id:)
+      StoryDataWrapper.from_json(get_request("creators/#{creator_id}/stories").body)
+    end
+  end
+end