supercast 0.0.2

data/lib/supercast/operations/save.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Supercast
+  module Operations
+    module Save
+      module ClassMethods
+        # Updates an API resource
+        #
+        # Updates the identified resource with the passed in parameters.
+        #
+        # ==== Attributes
+        #
+        # * +id+ - ID of the resource to update.
+        # * +params+ - A hash of parameters to pass to the API
+        # * +opts+ - A Hash of additional options (separate from the params /
+        #   object values) to be added to the request.
+        def update(id, params = {}, opts = {})
+          params.each_key do |k|
+            raise ArgumentError, "Cannot update protected field: #{k}" if protected_fields.include?(k)
+          end
+
+          resp, opts = request(:patch, "#{resource_url}/#{id}", Hash[object_name => params], opts)
+          Util.convert_to_supercast_object(resp.data, opts)
+        end
+      end
+
+      # Creates or updates an API resource.
+      #
+      # If the resource doesn't yet have an assigned ID and the resource is one
+      # that can be created, then the method attempts to create the resource.
+      # The resource is updated otherwise.
+      #
+      # ==== Attributes
+      #
+      # * +params+ - Overrides any parameters in the resource's serialized data
+      #   and includes them in the create or update. If +:req_url:+ is included
+      #   in the list, it overrides the update URL used for the create or
+      #   update.
+      # * +opts+ - A Hash of additional options (separate from the params /
+      #   object values) to be added to the request.
+      def save(params = {}, opts = {})
+        update_attributes(params)
+
+        # Now remove any parameters that look like object attributes.
+        params = params.reject { |k, _| respond_to?(k) }
+
+        values = serialize_params(self).merge(params)
+
+        # note that id gets removed here our call to #url above has already
+        # generated a uri for this object with an identifier baked in
+        values.delete(:id)
+
+        resp, opts = request(save_verb, save_url, Hash[object_name => values], opts)
+        initialize_from(resp.data, opts)
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      private
+
+      def save_verb
+        # This switch essentially allows us "upsert"-like functionality. If the
+        # API resource doesn't have an ID set (suggesting that it's new) and
+        # its class responds to .create (which comes from
+        # Supercast::Operations::Create), then use the verb to create a new
+        # resource, otherwise use the verb to update a resource.
+        self[:id].nil? && self.class.respond_to?(:create) ? :post : :patch
+      end
+
+      def save_url
+        # This switch essentially allows us "upsert"-like functionality. If the
+        # API resource doesn't have an ID set (suggesting that it's new) and
+        # its class responds to .create (which comes from
+        # Supercast::Operations::Create), then use the URL to create a new
+        # resource. Otherwise, generate a URL based on the object's identifier
+        # for a normal update.
+        if self[:id].nil? && self.class.respond_to?(:create)
+          self.class.resource_url
+        else
+          resource_url
+        end
+      end
+    end
+  end
+end

data/lib/supercast/resource.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Supercast
+  class Resource < DataObject
+    include Supercast::Operations::Request
+
+    def self.class_name
+      name.split('::')[-1]
+    end
+
+    def self.resource_url
+      if self == Resource
+        raise NotImplementedError,
+              'Resource is an abstract class. You should perform actions ' \
+              'on its subclasses (Episode, Creator, etc.)'
+      end
+
+      "/#{self::OBJECT_NAME.downcase}s"
+    end
+
+    def self.object_name
+      self::OBJECT_NAME
+    end
+
+    # Adds a custom method to a resource class. This is used to add support for
+    # non-CRUD API requests. custom_method takes the following parameters:
+    # - name: the name of the custom method to create (as a symbol)
+    # - http_verb: the HTTP verb for the API request (:get, :post, or :delete)
+    # - http_path: the path to append to the resource's URL. If not provided,
+    #              the name is used as the path
+    #
+    # For example, this call:
+    #     custom_method :suspend, http_verb: post
+    # adds a `suspend` class method to the resource class that, when called,
+    # will send a POST request to `/<object_name>/suspend`.
+    def self.custom_method(name, http_verb:, http_path: nil)
+      unless %i[get patch post delete].include?(http_verb)
+        raise ArgumentError,
+              "Invalid http_verb value: #{http_verb.inspect}. Should be one " \
+              'of :get, :patch, :post or :delete.'
+      end
+
+      http_path ||= name.to_s
+
+      define_singleton_method(name) do |id, params = {}, opts = {}|
+        url = "#{resource_url}/#{CGI.escape(id.to_s)}/#{CGI.escape(http_path)}"
+        resp, opts = request(http_verb, url, params, opts)
+        Util.convert_to_supercast_object(resp.data, opts)
+      end
+    end
+
+    def self.retrieve(id, opts = {})
+      opts = Util.normalize_opts(opts)
+      instance = new(id, opts)
+      instance.refresh
+      instance
+    end
+
+    def resource_url
+      unless (id = self['id'])
+        raise InvalidRequestError.new(
+          "Could not determine which URL to request: #{self.class} instance " \
+          "has invalid ID: #{id.inspect}",
+          'id'
+        )
+      end
+      "#{self.class.resource_url}/#{CGI.escape(id.to_s)}"
+    end
+
+    def object_name
+      self.class::OBJECT_NAME
+    end
+
+    def refresh
+      resp, opts = request(:get, resource_url, @retrieve_params)
+      initialize_from(resp.data, opts)
+    end
+  end
+end

data/lib/supercast/resources/channel.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Supercast
+  class Channel < Singleton
+    include Supercast::Operations::Save
+
+    OBJECT_NAME = 'channel'
+  end
+end

data/lib/supercast/resources/creator.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Supercast
+  class Creator < Resource
+    include Supercast::Operations::Destroy
+    extend Supercast::Operations::List
+    include Supercast::Operations::Save
+
+    OBJECT_NAME = 'creator'
+  end
+end

data/lib/supercast/resources/episode.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Supercast
+  class Episode < Resource
+    extend Supercast::Operations::Create
+    include Supercast::Operations::Destroy
+    extend Supercast::Operations::List
+    include Supercast::Operations::Save
+
+    OBJECT_NAME = 'episode'
+  end
+end

data/lib/supercast/resources/invite.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Supercast
+  class Invite < Resource
+    include Supercast::Operations::Destroy
+    extend Supercast::Operations::List
+
+    OBJECT_NAME = 'invite'
+  end
+end

data/lib/supercast/resources/role.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Supercast
+  class Role < Resource
+    extend Supercast::Operations::Create
+    include Supercast::Operations::Destroy
+    extend Supercast::Operations::List
+    include Supercast::Operations::Save
+
+    OBJECT_NAME = 'role'
+  end
+end

data/lib/supercast/resources/subscriber.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Supercast
+  class Subscriber < Resource
+    extend Supercast::Operations::Create
+    include Supercast::Operations::Destroy
+    extend Supercast::Operations::List
+    include Supercast::Operations::Save
+
+    OBJECT_NAME = 'subscriber'
+  end
+end

data/lib/supercast/resources/usage_alert.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Supercast
+  class UsageAlert < Resource
+    extend Supercast::Operations::List
+
+    OBJECT_NAME = 'usage_alert'
+
+    custom_method :dismiss, http_verb: :patch
+    custom_method :ignore, http_verb: :patch
+    custom_method :suspend, http_verb: :patch
+
+    def dismiss(params = {}, opts = {})
+      resp, opts = request(:patch, resource_url + '/dismiss', params, opts)
+      initialize_from(resp.data, opts)
+    end
+
+    def ignore(params = {}, opts = {})
+      resp, opts = request(:patch, resource_url + '/ignore', params, opts)
+      initialize_from(resp.data, opts)
+    end
+
+    def suspend(params = {}, opts = {})
+      resp, opts = request(:patch, resource_url + '/suspend', params, opts)
+      initialize_from(resp.data, opts)
+    end
+  end
+end

data/lib/supercast/resources.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require_relative 'resources/channel'
+require_relative 'resources/creator'
+require_relative 'resources/episode'
+require_relative 'resources/invite'
+require_relative 'resources/role'
+require_relative 'resources/subscriber'
+require_relative 'resources/usage_alert'

data/lib/supercast/response.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Supercast
+  # Response encapsulates some vitals of a response that came back from
+  # the Supercast API.
+  class Response
+    # The data contained by the HTTP body of the response deserialized from
+    # JSON.
+    attr_accessor :data
+
+    # The raw HTTP body of the response.
+    attr_accessor :http_body
+
+    # A Hash of the HTTP headers of the response.
+    attr_accessor :http_headers
+
+    # The integer HTTP status code of the response.
+    attr_accessor :http_status
+
+    # Initializes a Response object from a Hash like the kind returned as
+    # part of a Faraday exception.
+    #
+    # This may throw JSON::ParserError if the response body is not valid JSON.
+    def self.from_faraday_hash(http_resp)
+      resp = Response.new
+      resp.data = JSON.parse(http_resp[:body], symbolize_names: true)
+      resp.http_body = http_resp[:body]
+      resp.http_headers = http_resp[:headers]
+      resp.http_status = http_resp[:status]
+      resp
+    end
+
+    # Initializes a Response object from a Faraday HTTP response object.
+    #
+    # This may throw JSON::ParserError if the response body is not valid JSON.
+    def self.from_faraday_response(http_resp)
+      # handle no content responses
+      body = http_resp.body.empty? ? '{}' : http_resp.body
+
+      resp = Response.new
+      resp.data = JSON.parse(body, symbolize_names: true)
+      resp.http_body = body
+      resp.http_headers = http_resp.headers
+      resp.http_status = http_resp.status
+      resp
+    end
+  end
+end

data/lib/supercast/singleton.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Supercast
+  class Singleton < Resource
+    def self.resource_url
+      if self == Singleton
+        raise NotImplementedError,
+              'Singleton is an abstract class. You should ' \
+              'perform actions on its subclasses (Balance, etc.)'
+      end
+
+      "/#{self::OBJECT_NAME.downcase}"
+    end
+
+    def self.retrieve(opts = {})
+      instance = new(nil, Util.normalize_opts(opts))
+      instance.refresh
+      instance
+    end
+
+    def resource_url
+      self.class.resource_url
+    end
+  end
+end

data/lib/supercast/util.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+require 'cgi'
+
+module Supercast
+  module Util
+    # Options that a user is allowed to specify.
+    OPTS_USER_SPECIFIED = Set[
+      :api_key,
+    ].freeze
+
+    # Options that should be copyable from one DataObject to another
+    # including options that may be internal.
+    OPTS_COPYABLE = (
+      OPTS_USER_SPECIFIED + Set[:api_base]
+    ).freeze
+
+    # Options that should be persisted between API requests. This includes
+    # client, which is an object containing an HTTP client to reuse.
+    OPTS_PERSISTABLE = (
+      OPTS_USER_SPECIFIED + Set[:client]
+    ).freeze
+
+    def self.objects_to_ids(obj)
+      case obj
+      when Resource
+        obj.id
+      when Hash
+        res = {}
+        obj.each { |k, v| res[k] = objects_to_ids(v) unless v.nil? }
+        res
+      when Array
+        obj.map { |v| objects_to_ids(v) }
+      else
+        obj
+      end
+    end
+
+    def self.object_classes
+      @object_classes ||= Supercast::DataTypes.object_names_to_classes
+    end
+
+    # Converts a hash of fields or an array of hashes into a +DataObject+ or
+    # array of +DataObject+s. These new objects will be created as a concrete
+    # type as dictated by their `object` field (e.g. an `object` value of
+    # `creator` would create an instance of +Creator+), but if `object` is not
+    # present or of an unknown type, the newly created instance will fall back
+    # to being a +DataObject+.
+    #
+    # ==== Attributes
+    #
+    # * +data+ - Hash of fields and values to be converted into a DataObject.
+    # * +opts+ - Options for +DataObject+ like an API key that will be reused
+    #   on subsequent API calls.
+    def self.convert_to_supercast_object(data, opts = {})
+      opts = normalize_opts(opts)
+
+      case data
+      when Array
+        data.map { |i| convert_to_supercast_object(i, opts) }
+      when Hash
+        # Try converting to a known object class. If none available, fall back
+        # to generic DataObject
+        object_classes.fetch(data[:object], DataObject).construct_from(data, opts)
+      else
+        data
+      end
+    end
+
+    def self.log_error(message, data = {})
+      log_at_level(Supercast::LEVEL_ERROR, message, data, color: :cyan)
+    end
+
+    def self.log_info(message, data = {})
+      log_at_level(Supercast::LEVEL_INFO, message, data, color: :cyan)
+    end
+
+    def self.log_debug(message, data = {})
+      log_at_level(Supercast::LEVEL_DEBUG, message, data, color: :blue)
+    end
+
+    def self.symbolize_names(object)
+      case object
+      when Hash
+        new_hash = {}
+        object.each do |key, value|
+          key = (begin
+                   key.to_sym
+                 rescue StandardError
+                   key
+                 end) || key
+          new_hash[key] = symbolize_names(value)
+        end
+        new_hash
+      when Array
+        object.map { |value| symbolize_names(value) }
+      else
+        object
+      end
+    end
+
+    # Encodes a hash of parameters in a way that's suitable for use as query
+    # parameters in a URI or as form parameters in a request body. This mainly
+    # involves escaping special characters from parameter keys and values (e.g.
+    # `&`).
+    def self.encode_parameters(params)
+      Util.flatten_params(params)
+          .map { |k, v| "#{url_encode(k)}=#{url_encode(v)}" }.join('&')
+    end
+
+    # Encodes a string in a way that makes it suitable for use in a set of
+    # query parameters in a URI or in a set of form parameters in a request
+    # body.
+    def self.url_encode(key)
+      CGI.escape(key.to_s).
+        # Don't use strict form encoding by changing the square bracket control
+        # characters back to their literals. This is fine by the server, and
+        # makes these parameter strings easier to read.
+        gsub('%5B', '[').gsub('%5D', ']')
+    end
+
+    def self.flatten_params(params, parent_key = nil)
+      result = []
+
+      # do not sort the final output because arrays (and arrays of hashes
+      # especially) can be order sensitive, but do sort incoming parameters
+      params.each do |key, value|
+        calculated_key = parent_key ? "#{parent_key}[#{key}]" : key.to_s
+        if value.is_a?(Hash)
+          result += flatten_params(value, calculated_key)
+        elsif value.is_a?(Array)
+          result += flatten_params_array(value, calculated_key)
+        else
+          result << [calculated_key, value]
+        end
+      end
+
+      result
+    end
+
+    def self.flatten_params_array(value, calculated_key)
+      result = []
+      value.each_with_index do |elem, i|
+        if elem.is_a?(Hash)
+          result += flatten_params(elem, "#{calculated_key}[#{i}]")
+        elsif elem.is_a?(Array)
+          result += flatten_params_array(elem, calculated_key)
+        else
+          result << ["#{calculated_key}[#{i}]", elem]
+        end
+      end
+      result
+    end
+
+    def self.normalize_id(id)
+      if id.is_a?(Hash) # overloaded id
+        params_hash = id.dup
+        id = params_hash.delete(:id)
+      else
+        params_hash = {}
+      end
+      [id, params_hash]
+    end
+
+    # The secondary opts argument can either be a string or hash
+    # Turn this value into an api_key and a set of headers
+    def self.normalize_opts(opts)
+      case opts
+      when String
+        { api_key: opts }
+      when Hash
+        check_api_key!(opts.fetch(:api_key)) if opts.key?(:api_key)
+        opts.clone
+      else
+        raise TypeError, 'normalize_opts expects a string or a hash'
+      end
+    end
+
+    def self.check_string_argument!(key)
+      raise TypeError, 'argument must be a string' unless key.is_a?(String)
+
+      key
+    end
+
+    def self.check_api_key!(key)
+      raise TypeError, 'api_key must be a string' unless key.is_a?(String)
+
+      key
+    end
+
+    # Normalizes header keys so that they're all lower case and each
+    # hyphen-delimited section starts with a single capitalized letter. For
+    # example, `request-id` becomes `Request-Id`. This is useful for extracting
+    # certain key values when the user could have set them with a variety of
+    # diffent naming schemes.
+    def self.normalize_headers(headers)
+      headers.each_with_object({}) do |(k, v), new_headers|
+        k = k.to_s.tr('_', '-') if k.is_a?(Symbol)
+        k = k.split('-').reject(&:empty?).map(&:capitalize).join('-')
+
+        new_headers[k] = v
+      end
+    end
+
+    # Constant time string comparison to prevent timing attacks
+    # Code borrowed from ActiveSupport
+    def self.secure_compare(str_a, str_b)
+      return false unless str_a.bytesize == str_b.bytesize
+
+      l = str_a.unpack "C#{str_a.bytesize}"
+
+      res = 0
+      str_b.each_byte { |byte| res |= byte ^ l.shift }
+      res.zero?
+    end
+
+    #
+    # private
+    #
+
+    COLOR_CODES = {
+      black: 0, light_black:   60,
+      red: 1, light_red:     61,
+      green: 2, light_green:   62,
+      yellow: 3, light_yellow:  63,
+      blue: 4, light_blue:    64,
+      magenta: 5, light_magenta: 65,
+      cyan: 6, light_cyan:    66,
+      white: 7, light_white:   67,
+      default: 9
+    }.freeze
+    private_constant :COLOR_CODES
+
+    # Uses an ANSI escape code to colorize text if it's going to be sent to a
+    # TTY.
+    def self.colorize(val, color, isatty)
+      return val unless isatty
+
+      mode = 0 # default
+      foreground = 30 + COLOR_CODES.fetch(color)
+      background = 40 + COLOR_CODES.fetch(:default)
+
+      "\033[#{mode};#{foreground};#{background}m#{val}\033[0m"
+    end
+    private_class_method :colorize
+
+    # Turns an integer log level into a printable name.
+    def self.level_name(level)
+      case level
+      when LEVEL_DEBUG then 'debug'
+      when LEVEL_ERROR then 'error'
+      when LEVEL_INFO  then 'info'
+      else level
+      end
+    end
+    private_class_method :level_name
+
+    def self.log_at_level(level, message, data = {}, opts = {})
+      log_internal(message, data, { level: level, logger: Supercast.logger, out: $stdout }.merge(opts)) if !Supercast.logger.nil? || !Supercast.log_level.nil? && Supercast.log_level <= level
+    end
+    private_class_method :log_at_level
+
+    # TODO: Make these named required arguments when we drop support for Ruby
+    # 2.0.
+    def self.log_internal(message, data = {}, color: nil, level: nil, logger: nil, out: nil)
+      data_str = data.reject { |_k, v| v.nil? }
+                     .map do |(k, v)|
+        format('%<key>s=%<value>s',
+               key: colorize(k, color, logger.nil? && !out.nil? && out.isatty),
+               value: wrap_logfmt_value(v))
+      end.join(' ')
+
+      if !logger.nil?
+        # the library's log levels are mapped to the same values as the
+        # standard library's logger
+        logger.log(level,
+                   format('message=%<message>s %<data_str>s',
+                          message: wrap_logfmt_value(message),
+                          data_str: data_str))
+      elsif out.isatty
+        out.puts format('%<level>s %<message>s %<data_str>s',
+                        level: colorize(level_name(level)[0, 4].upcase,
+                                        color, out.isatty),
+                        message: message,
+                        data_str: data_str)
+      else
+        out.puts format('message=%<message>s level=%<level>s %<data_str>s',
+                        message: wrap_logfmt_value(message),
+                        level: level_name(level),
+                        data_str: data_str)
+      end
+    end
+    private_class_method :log_internal
+
+    # Wraps a value in double quotes if it looks sufficiently complex so that
+    # it can be read by logfmt parsers.
+    def self.wrap_logfmt_value(val)
+      # If value is any kind of number, just allow it to be formatted directly
+      # to a string (this will handle integers or floats).
+      return val if val.is_a?(Numeric)
+
+      # Hopefully val is a string, but protect in case it's not.
+      val = val.to_s
+
+      if %r{[^\w\-/]}.match?(val)
+        # If the string contains any special characters, escape any double
+        # quotes it has, remove newlines, and wrap the whole thing in quotes.
+        format(%("%<value>s"), value: val.gsub('"', '\"').delete("\n"))
+      else
+        # Otherwise use the basic value if it looks like a standard set of
+        # characters (and allow a few special characters like hyphens, and
+        # slashes)
+        val
+      end
+    end
+    private_class_method :wrap_logfmt_value
+  end
+end

data/lib/supercast/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Supercast
+  VERSION = '0.0.2'
+end