talis 0.12.0

data/lib/talis/bibliography/result_set.rb

@@ -0,0 +1,34 @@
+require 'forwardable'
+module Talis
+  module Bibliography
+    # Provides convenience methods for working with MetatronClient::*ResultSets
+    # TODO: eventually this will be replaced with PaginatedJsonApiArray from
+    # Atlas
+    module ResultSet
+      include Enumerable
+      extend Forwardable
+      def_delegators :@data, :[], :each, :first, :last, :find, :find_all
+
+      # Replaces the MetatronClient objects with more intuitive DSL objects
+      # and hydrates the relationships from the included array, if available
+      def hydrate
+        model_data
+        self
+      end
+
+      private
+
+      def model_data
+        data.each_with_index do |data, i|
+          if is_a? MetatronClient::WorkResultSet
+            resource = Work.new data
+          elsif is_a? MetatronClient::ManifestationResultSet
+            resource = Manifestation.new data
+          end
+          resource.hydrate_relationships(included) if included
+          self.data[i] = resource
+        end
+      end
+    end
+  end
+end

data/lib/talis/bibliography/work.rb

@@ -0,0 +1,164 @@
+require 'metatron_ruby_client'
+require 'forwardable'
+
+module Talis
+  module Bibliography
+    # Represents bibliographic works API operations provided by the Metatron gem
+    # {https://github.com/talis/metatron_rb}
+    #
+    # In order to perform remote operations, the client must be configured
+    # with a valid OAuth client that is allowed to query nodes:
+    #
+    #  Talis::Authentication.client_id = 'client_id'
+    #  Talis::Authentication.client_secret = 'client_secret'
+    #
+    class Work < Talis::Resource
+      extend Forwardable, Talis::OAuthService, Talis::Bibliography
+      base_uri Talis::METATRON_HOST
+      attr_reader :manifestations, :assets, :work_data
+      attr_accessor :id, :type, :title
+      def_delegators :@work_data, :id, :type
+
+      # rubocop:disable Metrics/LineLength
+      class << self
+        # Search for bibliographic works
+        # @param request_id [String] ('uuid') unique ID for the remote request.
+        # @param query [String] the query to filter works on
+        # @param include [Array] the related resources to associate with each work
+        #   see {https://github.com/talis/metatron_rb/blob/master/docs/DefaultApi.md#2_works_get}
+        # @param opts [Hash] Can include key/value pairs for offset (default: 0),
+        #   limit (default 20), and escape_query (boolean), which will escape any
+        #   reserved characters from the query parameter
+        # @return [MetatronClient::WorkResultSet] containing data and meta attributes.
+        #   The structure is as follows:
+        #     {
+        #       data: [work1, work2, work3, work4, work5],
+        #       meta: { offset: 0, count: 20, limit: 5 }
+        #       included: [manifestation|assset1, manifestation|assset2]
+        #     }
+        #  where works are of type Talis::Bibliography::Work, which are also available
+        # directly via the Enumerable methods: each, find, find_all, first, last
+        # @raise [Talis::ClientError] if the request was invalid.
+        # @raise [Talis::ServerError] if the search failed on the
+        #   server.
+        # @raise [Talis::ServerCommunicationError] for network issues.
+        def find(request_id: new_req_id, query:, include: [], opts: {})
+          query = escape_query(query) if opts[:escape_query]
+          offset = opts[:offset] || 0
+          limit = opts[:limit] || 20
+          search_works(request_id, query, offset, limit, include)
+        rescue MetatronClient::ApiError => error
+          begin
+            handle_response(error)
+          rescue Talis::NotFoundError
+            empty_result(offset, limit)
+          end
+        end
+
+        # Fetch a single work by id
+        # @param request_id [String] ('uuid') unique ID for the remote request.
+        # @param id [String] the ID of the work to fetch.
+        # @return Talis::Bibliography::Work or nil if the work cannot be found.
+        # @raise [Talis::ClientError] if the request was invalid.
+        # @raise [Talis::ServerError] if the fetch failed on the
+        #   server.
+        # @raise [Talis::ServerCommunicationError] for network issues.
+        def get(request_id: new_req_id, id:)
+          new api_client(request_id).works_work_id_assets_get(id, token).data
+        rescue MetatronClient::ApiError => error
+          begin
+            handle_response(error)
+          rescue Talis::NotFoundError
+            nil
+          end
+        end
+
+        private
+
+        def search_works(request_id, query, offset, limit, include)
+          api_client(request_id).work(token, query, limit,
+                                      offset, include: include)
+                                .extend(ResultSet).hydrate
+        end
+
+        def empty_result(offset, limit)
+          empty_result_set(MetatronClient::WorkResultSet,
+                           offset: offset, limit: limit, count: 0)
+        end
+      end
+
+      def initialize(work_data = nil)
+        if work_data.is_a? MetatronClient::WorkData
+          parse_work_data work_data
+        else
+          @work_data = MetatronClient::WorkData.new
+        end
+      end
+
+      # TODO: call manifestation route if not set
+      def manifestations
+        @manifestations ||= []
+      end
+
+      # TODO: call assets route if not set
+      def assets
+        @assets ||= []
+      end
+
+      # By default, the metatron client returns generic ResourceLink objects
+      # as the related resources.  When passed an array of Metatron::ResourceData
+      # objects, it will replace the ResourceLink objects with more appropriately
+      # typed objects
+      # @param resources [Array] an array of Metatron::ResourceData objects
+      def hydrate_relationships(resources)
+        manifestations.map! do |m|
+          resource = find_relationship_in_included m.manifestation_data.to_hash,
+                                                   resources
+          return m unless resource
+          hydrate_manifestation_assets resource, resources
+          Manifestation.new(MetatronClient::ManifestationData.new(
+                              resource.to_hash
+          ))
+        end
+        nil
+      end
+
+      private
+
+      def hydrate_manifestation_assets(manifestation, resources)
+        if manifestation_has_assets? manifestation
+          manifestation.relationships[:assets][:data].each do |asset_data|
+            asset = find_relationship_in_included asset_data.to_hash, resources
+            assets << MetatronClient::AssetData.new(asset.to_hash) if asset
+          end
+        end
+        nil
+      end
+
+      def manifestation_has_assets?(manifestation)
+        manifestation.try(:relationships) &&
+          manifestation.relationships[:assets] &&
+          manifestation.relationships[:assets][:data]
+      end
+
+      def find_relationship_in_included(resource_data, included)
+        included.find do |resource|
+          resource.id == resource_data[:id] && resource.type == resource_data[:type]
+        end
+      end
+
+      def parse_work_data(work_data)
+        @work_data = work_data
+        @title = work_data.try(:attributes).try(:titles)
+
+        if work_data.try(:relationships).try(:manifestations).try(:data)
+          work_data.relationships.manifestations.data.each do |manifestation|
+            manifestations << Manifestation.new(
+              MetatronClient::ManifestationData.new(manifestation.to_hash)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/talis/constants.rb

@@ -0,0 +1,9 @@
+module Talis
+  BABEL_HOST = 'https://feeds.talis.com'.freeze
+  BLUEPRINT_HOST = 'https://hierarchy.talis.com'.freeze
+  ECHO_HOST = 'https://analytics.talis.com'.freeze
+  METATRON_HOST = 'https://bibliography.talis.com'.freeze
+  PERSONA_HOST = 'https://users.talis.com'.freeze
+
+  EBOOK_TYPE = 'ebook_inventory'.freeze
+end

data/lib/talis/errors.rb

@@ -0,0 +1,10 @@
+module Talis
+  # All errors will extend from this base class.
+  class Error < StandardError
+  end
+end
+
+require_relative 'errors/authentication_failed_error'
+require_relative 'errors/client_errors'
+require_relative 'errors/server_error'
+require_relative 'errors/server_communication_error'

data/lib/talis/errors/authentication_failed_error.rb

@@ -0,0 +1,4 @@
+module Talis
+  class AuthenticationFailedError < Talis::Error
+  end
+end

data/lib/talis/errors/client_errors.rb

@@ -0,0 +1,19 @@
+module Talis
+  class ClientError < Talis::Error
+  end
+
+  class BadRequestError < ClientError
+  end
+
+  class UnauthorizedError < ClientError
+  end
+
+  class ForbiddenError < ClientError
+  end
+
+  class NotFoundError < ClientError
+  end
+
+  class ConflictError < ClientError
+  end
+end

data/lib/talis/errors/server_communication_error.rb

@@ -0,0 +1,4 @@
+module Talis
+  class ServerCommunicationError < Talis::Error
+  end
+end

data/lib/talis/errors/server_error.rb

@@ -0,0 +1,4 @@
+module Talis
+  class ServerError < Talis::Error
+  end
+end

data/lib/talis/extensions/object.rb

@@ -0,0 +1,11 @@
+# Helper functions for objects
+class Object
+  def blank?
+    subject = respond_to?(:trim) ? strip : self
+    subject.respond_to?(:empty?) ? subject.empty? : !subject
+  end
+
+  def present?
+    !blank?
+  end
+end

data/lib/talis/feeds.rb

@@ -0,0 +1,8 @@
+require_relative 'feeds/annotation'
+require_relative 'feeds/feed'
+
+module Talis
+  # Represents a collection of classes used to work with annotations and feeds.
+  module Feed
+  end
+end

data/lib/talis/feeds/annotation.rb

@@ -0,0 +1,129 @@
+module Talis
+  module Feeds
+    # Represents an annotation, for example, a video resource comment.
+    class Annotation < Talis::Resource
+      base_uri Talis::BABEL_HOST
+      attr_reader :id, :body, :target, :annotated_by, :motivated_by,
+                  :expires_at, :user
+
+      # Creates a new annotation object. For internal use only,
+      # use {Annotation.create}.
+      # @param data [Hash] The incoming annotation data to construct
+      #  a new annotation object with.
+      # @param user [Talis::User](nil) The user that created the annotation.
+      #  This will be nil for an annotation that has not been hydrated.
+      #  Hydrated data is provided by feeds.
+      def initialize(data, user: nil)
+        # Symbolise all keys for consistency between what was provided
+        # and what is returned.
+        data = JSON.parse(JSON[data], symbolize_names: true)
+        @id = data[:_id]
+        @body = data[:hasBody]
+        @target = data[:hasTarget].map { |target| underscore(target) }
+        @annotated_by = data[:annotatedBy]
+        @motivated_by = data[:motivatedBy]
+        @expires_at = data[:expiresAt]
+        @user = user
+      end
+
+      private
+
+      def underscore(payload)
+        payload.map { |key, value| [key.to_s.underscore.to_sym, value] }.to_h
+      end
+
+      class << self
+        # Create a new annotation that is persisted.
+        # @param opts [Hash] The annotation data used to create the annotation:
+        #  {
+        #    request_id: 'optional unique ID for the remote request'
+        #    body: {
+        #      format: 'e.g: text/plain',
+        #      type: 'e.g: Text',
+        #      chars: 'annotation content',
+        #      details: {} # optional hash to provide additional details.
+        #    },
+        #    target: [
+        #      {
+        #        uri: 'location of target being annotated',
+        #        as_referenced_by: 'optional reference location',
+        #        fragment: 'optional fragment within location'
+        #      }
+        #    ]
+        #    annotated_by: 'Talis user GUID performing the annotation',
+        #    motivated_by: 'optional motivation string',
+        #    expires_at: 'optional ISO 8601 date time string'
+        #  }
+        # @return [Talis::Feeds::Annotation] The persisted annotation.
+        # @raise [Talis::ClientError] if the request was invalid.
+        # @raise [Talis::ServerError] if there was a problem with the request.
+        # @raise [Talis::ServerCommunicationError] for network issues.
+        # @raise [ArgumentError] for validation errors against opts.
+        def create(opts)
+          validate_annotation opts
+          new handle_response(post_annotation(opts))
+        rescue SocketError
+          raise Talis::ServerCommunicationError
+        end
+
+        private
+
+        def validate_annotation(annotation)
+          min_required = 'annotation must contain body, target and annotated_by'
+          required = [:body, :target, :annotated_by]
+          provided = annotation.select { |attr| required.include? attr }.keys
+          raise ArgumentError, min_required unless required == provided
+          validate_targets(annotation)
+          validate_expiry(annotation)
+        end
+
+        def validate_targets(annotation)
+          targets = annotation[:target]
+          raise ArgumentError,
+                'annotation target must be an array' unless targets.is_a? Array
+          targets.each do |target|
+            raise ArgumentError,
+                  'annotation targets must contain uri' unless target[:uri]
+            raise ArgumentError,
+                  'target uri must be a string' unless target[:uri].is_a? String
+          end
+        end
+
+        def validate_expiry(annotation)
+          expiry = annotation[:expires_at]
+          Time.iso8601(expiry) if expiry
+        rescue StandardError
+          raise ArgumentError, 'expired_at must be a valid ISO 8601 date'
+        end
+
+        def post_annotation(opts)
+          request_id = opts[:request_id] || new_req_id
+          post('/annotations',
+               headers: {
+                 'Content-Type' => 'application/json',
+                 'X-Request-Id' => request_id,
+                 'Authorization' => "Bearer #{token}"
+               },
+               body: body(opts).to_json)
+        end
+
+        def body(opts)
+          min_body = {
+            hasBody: opts[:body],
+            hasTarget: opts[:target].map { |target| camelize(target) },
+            annotatedBy: opts[:annotated_by]
+          }
+          min_body[:expiresAt] = opts[:expires_at] if opts[:expires_at]
+          min_body[:motivatedBy] = opts[:motivated_by] if opts[:motivated_by]
+          min_body
+        end
+
+        def camelize(payload)
+          payload.map do |key, value|
+            [key.to_s.camelize(:lower).to_sym, value]
+          end.to_h
+        end
+      end
+    end
+  end
+end

data/lib/talis/feeds/feed.rb

@@ -0,0 +1,58 @@
+module Talis
+  module Feeds
+    # Represents a feed, as a way of bringing back a collection of annotations.
+    class Feed < Talis::Resource
+      base_uri Talis::BABEL_HOST
+
+      class << self
+        # Returns a collection of annotations matching the provided target.
+        # @param request_id [String] ('uuid') unique ID for the remote request.
+        # @param target_uri [String] The URI uniquely identifying the target.
+        # @return [Array<Talis::Feeds::Annotation>] An array of annotations
+        #  or an empty array if the feed was not found.
+        # @raise [Talis::ClientError] if the request was invalid.
+        # @raise [Talis::ServerError] if there was a problem with the request.
+        # @raise [Talis::ServerCommunicationError] for network issues.
+        def find(request_id: new_req_id, target_uri:)
+          md5_target_uri = Digest::MD5.hexdigest(target_uri)
+          response = fetch_feed(request_id, md5_target_uri)
+          begin
+            build handle_response(response)
+          rescue Talis::NotFoundError
+            []
+          end
+        rescue SocketError
+          raise Talis::ServerCommunicationError
+        end
+
+        private
+
+        def fetch_feed(request_id, md5_target_uri)
+          get("/feeds/targets/#{md5_target_uri}/activity/annotations/hydrate",
+              headers: {
+                'Content-Type' => 'application/json',
+                'X-Request-Id' => request_id,
+                'Authorization' => "Bearer #{token}"
+              })
+        end
+
+        def build(response)
+          annotations = response['annotations']
+          annotations.map do |annotation|
+            Annotation.new(annotation, user: hydrate_user(annotation, response))
+          end
+        end
+
+        def hydrate_user(annotation_data, feed_data)
+          profiles = feed_data['userProfiles']
+          return unless profiles
+          guid = annotation_data['annotatedBy']
+          user = profiles[guid]
+          return unless user
+          Talis::User.build(guid: guid, first_name: user['first_name'],
+                            surname: user['surname'], email: user['email'])
+        end
+      end
+    end
+  end
+end