essential 0.9.0

data/lib/essential/messaging/message.rb

@@ -0,0 +1,68 @@
+module Essential::Messaging
+  class Message < Essential::Resource
+    extend Essential::Resource::Create
+    extend Essential::Resource::List
+    include Essential::Resource::Delete
+
+    attr_property :status, :body, :media_urls,
+                  :notified_received_at, :notified_received_result,
+                  :onstatus_url, :status_updated_at,
+                  :notified_status_at, :notified_status_result,
+                  :delivery_attempts, :delivery_attempted_at,
+                  :msecs_in_flight,
+                  :created_at, :updated_at
+
+    # Timestamps, one and all!
+    attr_schema [
+      :notified_received_at, :status_updated_at, :notified_status_at,
+      :delivery_attempted_at, :created_at, :updated_at
+    ].reduce({}) {|h,k| h[k] = Time; h}
+
+    # special aliases for create
+    attr_unfiltered :subscriber, :transport, :channel
+
+    attr_relation account_sid:    'Essential::Account'
+    attr_relation channel_sid:    'Channel'
+    attr_relation transport_sid:  'Transport'
+    attr_relation subscriber_sid: 'Subscriber'
+
+    alias :redact :delete
+
+    def self.status(params: {}, headers: @headers)
+      # permitted:
+      # :start_date, :end_date, :carrier, :status, :channel, :channel_sid
+      resp = self.request(
+        :get,
+        url: '/v2/account/messages/analytics/status',
+        params: params,
+        headers: headers
+      )
+      JSON.parse(resp)
+    end
+
+    def self.queue_status(params: {}, headers: @headers)
+      # permitted:
+      # :channel, :channel_name
+      resp = self.request(
+        :get,
+        url: '/v2/account/messages/analytics/queue_status',
+        params: params,
+        headers: headers
+      )
+      JSON.parse(resp)
+    end
+
+    def self.seconds_in_flight(params: {}, headers: @headers)
+      # permitted:
+      # :start_date, :end_date, :carrier
+      resp = self.request(
+        :get,
+        url: '/v2/account/messages/analytics/seconds_in_flight',
+        params: params,
+        headers: headers
+      )
+      JSON.parse(resp)
+    end
+
+  end
+end

data/lib/essential/messaging/property.rb

@@ -0,0 +1,27 @@
+module Essential::Messaging
+  class Property < Essential::Resource
+    include Essential::Resource::Update
+    include Essential::Resource::Delete
+
+    undef_method :sid
+    attr_property :subscriber_sid, :name, :value
+
+    def self.retrieve(*args)
+      raise NotImplementedError, 'must be retrieved from a Subscriber'
+    end
+
+    def self.url(subscriber_sid)
+      format('%s/%s/properties', Subscriber.url, CGI.escape(subscriber_sid))
+    end
+
+    def url
+      format('%s/%s', self.class.url(subscriber_sid), CGI.escape(name))
+    end
+
+    protected
+
+    def loaded?
+      @attributes.key?('name') && @attributes.key?('value')
+    end
+  end
+end

data/lib/essential/messaging/subscriber.rb

@@ -0,0 +1,64 @@
+module Essential::Messaging
+  class Subscriber < Essential::Resource
+    extend Essential::Resource::Create
+    extend Essential::Resource::List
+    include Essential::Resource::Update
+    include Essential::Resource::Delete
+
+    attr_property :phone_number, :status, :carrier,
+                  :subscribed_at, :unsubscribed_at, :created_at, :updated_at
+
+    # special aliases for create
+    attr_unfiltered :transport, :channel
+
+    attr_schema subscribed_at: Time, unsubscribed_at: Time, created_at: Time, updated_at: Time
+
+    attr_relation account_sid:   'Essential::Account'
+    attr_relation channel_sid:   'Channel'
+    attr_relation transport_sid: 'Transport'
+
+    alias :unsubscribe :delete
+
+    def messages
+      Essential::Resource::PaginatorProxy.new(
+        Message,
+        params: {subscriber: self.sid},
+        headers: @headers
+      )
+    end
+
+    def properties
+      Essential::Resource::PaginatorProxy.new(
+        Property,
+        url: Property.url(self.sid),
+        headers: @headers,
+        attrs: {subscriber_sid: self.sid},
+      )
+    end
+
+    def self.by_carrier(params: {}, headers: @headers)
+      # permitted:
+      # :start_date, :end_date, :carrier
+      resp = self.request(
+        :get,
+        url: '/v2/account/subscribers/analytics/by_carrier',
+        params: params,
+        headers: headers
+      )
+      JSON.parse(resp)
+    end
+
+    def self.by_transport(params: {}, headers: @headers)
+      # permitted:
+      # :start_date, :end_date, :carrier
+      resp = self.request(
+        :get,
+        url: '/v2/account/subscribers/analytics/by_transport',
+        params: params,
+        headers: headers
+      )
+      JSON.parse(resp)
+    end
+
+  end
+end

data/lib/essential/messaging/transport.rb

@@ -0,0 +1,29 @@
+module Essential::Messaging
+  class Transport < Essential::Resource
+    extend Essential::Resource::List
+
+    attr_property :protocol, :endpoint, :created_at, :updated_at
+    attr_schema created_at: Time, updated_at: Time
+
+    attr_unfiltered :channel
+
+    attr_relation account_sid: 'Essential::Account'
+    attr_relation channel_sid: 'Channel'
+
+    def subscribers
+      Essential::Resource::PaginatorProxy.new(
+        Subscriber,
+        params: {transport: self.sid},
+        headers: @headers
+      )
+    end
+
+    def messages
+      Essential::Resource::PaginatorProxy.new(
+        Message,
+        params: {transport: self.sid},
+        headers: @headers
+      )
+    end
+  end
+end

data/lib/essential/resource.rb

@@ -0,0 +1,127 @@
+require 'essential/resource/attr_methods'
+require 'essential/resource/create'
+require 'essential/resource/list'
+require 'essential/resource/update'
+require 'essential/resource/delete'
+
+module Essential
+  class Resource
+    include AttrMethods
+
+    class << self
+      attr_reader :schema
+
+      def request(method, url: nil, params: nil, headers: nil)
+        if headers
+          headers = headers.clone
+          sid     = headers.delete(:sid)
+          token   = headers.delete(:token)
+        end
+
+        Essential.request(method, url, sid: sid, token: token, params: params, headers: headers)
+      end
+
+      protected
+
+      def class_name
+        self.name.split('::').last
+      end
+    end
+
+    attr_property :sid
+
+    def self.url
+      if self == Resource
+        raise NotImplementedError, 'Resource is an abstract class'
+      end
+      "/v2/account/#{CGI.escape(class_name.downcase)}s"
+    end
+
+    def url
+      raise ArgumentError, 'sid required' if sid.nil? || sid.empty?
+      format('%s/%s', self.class.url, CGI.escape(self.sid))
+    end
+
+    def initialize(sid: nil, attrs: nil, headers: nil)
+      init_from(attrs)
+      @attributes['sid'] = sid if sid
+      @headers = headers
+      self
+    end
+
+    def fetch(headers: @headers)
+      json = JSON.parse self.class.request(:get, url: self.url, headers: headers)
+      init_from json
+      self
+    end
+
+    def init_from(attributes)
+      attributes = (attributes || {}).clone
+
+      # reject reject keys that aren't actually our attrs
+      @attributes = filter_attrs(attributes)
+
+      if self.class.schema
+        self.class.schema.each do |key,type|
+          apply_schema(key, type)
+        end
+      end
+      self
+    end
+
+    def loaded?
+      @attributes.size > 1
+    end
+
+    def as_json(opts={})
+      @attributes.dup
+    end
+
+    def to_json(opts={})
+      as_json.to_json(opts)
+    end
+
+    def ==(other)
+      case other
+      when Essential::Resource
+        self.sid == other.sid
+      else
+        false
+      end
+    end
+
+    def inspect
+      format(
+        '#<%s:0x%s @attributes=%s>',
+        self.class.name,
+        (self.object_id << 1).to_s(16),
+        JSON.pretty_generate(@attributes)
+      )
+    end
+
+    protected
+    def [](key)
+      # realize attributes upon access
+      self.fetch unless :sid == key.to_sym || loaded?
+      @attributes[key]
+    end
+
+    def apply_schema(key, type)
+      if val = @attributes[key]
+        if type === val
+          return
+        elsif type.respond_to?(:parse)
+          val = type.parse(@attributes[key])
+          if type == Time && Essential.utc_offset
+            # coerce into local time
+            val = val.getlocal(Essential.utc_offset)
+          end
+          @attributes[key] = val
+        else
+          raise ArgumentError, format('unsure how to apply schema "%s"', type)
+        end
+      end
+    end
+
+  end
+end

data/lib/essential/resource/attr_methods.rb

@@ -0,0 +1,65 @@
+require 'essential/resource/attr_relations'
+
+module Essential
+  class Resource
+    module AttrMethods
+
+      module ClassMethods
+        include AttrRelations
+
+        def from_attributes(attributes, headers: @headers)
+          self.new(attrs: attributes, headers: headers)
+        end
+
+        def permitted_attrs
+          _permitted_attrs.dup
+        end
+
+        def filter_attrs(attributes)
+          filtered = {}
+          attributes.keys.each do |k|
+            if self.permitted_attrs.include?(k.to_sym)
+              filtered[k.to_s] = attributes[k]
+            end
+          end
+
+          filtered
+        end
+
+        protected
+
+        def _permitted_attrs
+          @permitted_attrs ||= Set[:sid]
+        end
+
+        def attr_property(*names)
+          attr_unfiltered(*names)
+          names.each do |name|
+            define_method(name.to_sym) do
+              self[name.to_s]
+            end
+          end
+        end
+
+        def attr_unfiltered(*names)
+          _permitted_attrs.merge names.map(&:to_sym)
+        end
+
+        def attr_schema(pairs)
+          @schema ||= {}
+          @schema = @schema.merge(Hash[pairs.map{|k,v| [k.to_s, v]}])
+        end
+
+      end
+
+      def filter_attrs(attributes)
+        self.class.filter_attrs(attributes)
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+    end
+  end
+end

data/lib/essential/resource/attr_relations.rb

@@ -0,0 +1,81 @@
+module Essential
+  class Resource
+    module AttrRelations
+
+      # Method for defining a mapping between a `sid` property and a Class.
+      #
+      def attr_relation(pairs)
+        pairs.each do |method, resource|
+          sid_method = method.to_sym
+
+          # Enforces that we're dealing with a `sid` property.
+          if method =~ /\A(.+)_sid\Z/
+            method = $1.to_sym
+          else
+            raise ArgumentError, 'attribute must end in _sid'
+          end
+
+          unless method_defined?(sid_method)
+            # perhaps we didn't explicitly define access to the sid - do so now.
+            attr_property sid_method
+          end
+
+          # Avoid circular load dependencies:
+          #
+          # `resource` might be a Class, or it might be a String.
+          #
+          # If it is a String, we'll attempt to turn it into a CLass.
+          # This will be done once - the first time it is accessed -
+          # to allow both classes to load completely before constantizing
+          # the String.
+          my_lazy_resource = format('lazy_%s_resource', method).to_sym
+          my_lazy_variable = format('@%s', my_lazy_resource).to_sym
+          define_singleton_method(my_lazy_resource) do
+            # only resolve this resource once
+            lazy_resource = instance_variable_get(my_lazy_variable)
+            unless lazy_resource
+              lazy_resource = resource
+
+              case lazy_resource
+              when String
+                if lazy_resource.include?('::')
+                  # this appears to be a fully-namespaced Resource
+                  lazy_resource = lazy_resource.split('::')
+                else
+                  # no namespace - assume it's part of the current class.
+                  namespace = self.name.split('::')
+                  namespace.pop
+                  namespace << lazy_resource
+                  lazy_resource = namespace
+                end
+                # fetch each module in turn
+                lazy_resource = lazy_resource.reduce(Object) {|o,c| o.const_get c}
+              end
+
+              # now that we have a class, ensure it is *actually* a Resource!
+              unless lazy_resource < Essential::Resource
+                raise ArgumentError, format('mapping must be an %s', Essential::Resource.name)
+              end
+
+              # cache it.
+              instance_variable_set(my_lazy_variable, lazy_resource)
+            end
+
+            lazy_resource
+          end
+
+          define_method(method) do
+            sid = send(sid_method)
+            if sid.nil?
+              nil
+            else
+              self.class.send(my_lazy_resource).new(sid: sid, headers: @headers)
+            end
+          end
+        end
+
+      end
+
+    end
+  end
+end