essential 0.9.0

data/lib/essential/resource/create.rb

@@ -0,0 +1,21 @@
+module Essential
+  class Resource
+    module Create
+
+      def create(params, headers: @headers)
+        params = (params || {}).clone
+        params = @params.merge(params) if @params
+        params = filter_attrs(params)
+        response = request(:post,
+                           url: url,
+                           params: params,
+                           headers: headers)
+        json = JSON.parse(response)
+        json = @params.merge(json) if @params
+        json = @attrs.merge(json)  if @attrs
+        from_attributes(json)
+      end
+
+    end
+  end
+end

data/lib/essential/resource/delete.rb

@@ -0,0 +1,20 @@
+module Essential
+  class Resource
+    module Delete
+
+      def delete(headers: @headers)
+        response = self.class.request(:delete, url: self.url, headers: headers)
+
+        if response.nil? || response.empty?
+          nil
+        else
+          json = JSON.parse(response)
+          json = @params.merge(json) if @params
+          json = @attrs.merge(json)  if @attrs
+          init_from(json)
+        end
+      end
+
+    end
+  end
+end

data/lib/essential/resource/list.rb

@@ -0,0 +1,17 @@
+module Essential
+  class Resource
+    module List
+
+      def retrieve(sid, fetch: true, headers: @headers)
+        me = self.new(sid: sid, headers: headers)
+        me.fetch() if fetch
+        me
+      end
+
+      def list(params: {}, url: nil, headers: @headers)
+        return PaginatorProxy.new(self, url: url, params: params, headers: headers)
+      end
+
+    end
+  end
+end

data/lib/essential/resource/paginator_proxy.rb

@@ -0,0 +1,115 @@
+module Essential
+  class Resource
+    class PaginatorProxy
+      include Create
+      include Enumerable
+
+      attr_reader :proxied_class, :url
+      attr_reader :headers, :params
+      attr_reader :total, :pages, :per_page
+      alias :size :total
+      alias :count :total
+
+      def initialize(proxied_class, url: nil, params: {}, headers: {}, attrs: {})
+        @fetched_pages = {}
+        @proxied_class = proxied_class
+        @url = url || @proxied_class.url
+        @params  = params  || {}
+        @headers = headers || {}
+        @attrs   = attrs   || {}
+
+        @total = 0
+        @pages = 0
+        @per_page = 0
+
+        self.refresh
+      end
+
+      def [](i)
+        i = i.to_i
+
+        # support reverse wrap
+        i += @total if i < 0
+
+        return nil if i >= @total || i < 0
+
+        page = (i / @per_page) + 1
+        index = i % @per_page
+
+        fetch_page(page) unless @fetched_pages.key?(page)
+        @fetched_pages[page][index]
+      end
+
+      def last
+        self[-1]
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        (0...self.total).each do |idx|
+          yield self[idx]
+        end
+      end
+
+      def refresh
+        @fetched_pages.clear
+        fetch_page(nil)
+      end
+
+      def as_json
+        self.map(&:as_json)
+      end
+
+      def inspect
+        format(
+          '#<%s:0x%s %s>',
+          self.class.name,
+          (self.object_id << 1).to_s(16),
+          [:total, :per_page, :headers, :params].map do |m|
+            attr = self.send(m)
+            if attr
+              format('@%s=%s', m, attr.inspect)
+            else
+              nil
+            end
+          end.compact.join(', ')
+        )
+      end
+
+      protected
+
+      def fetch_page(page)
+        params = (@params || {}).clone
+        params = {page: page}.merge(params) if page
+
+        # Actually touch the network
+        response = @proxied_class.request(
+          :get,
+          url: @url,
+          params: params,
+          headers: @headers
+        )
+
+        # update our paging information
+        @total    = response.headers[:total].to_i
+        @per_page = response.headers[:per_page].to_i
+        @pages    = (@total.to_f / @per_page).ceil
+
+        json = JSON.parse(response)
+        @fetched_pages[page || 1] = json.map do |json|
+          # persist @attrs across returned objects, as when listing a Subscriber Property.
+          attrs = @attrs.merge(json)
+          @proxied_class.from_attributes(attrs, headers: @headers)
+        end
+      end
+
+      private
+
+      def method_missing(method, *args, &block)
+        @proxied_class.send(method, *args, &block)
+      end
+
+    end
+  end
+end

data/lib/essential/resource/update.rb

@@ -0,0 +1,26 @@
+module Essential
+  class Resource
+    module Update
+
+      def update(params, headers: @headers)
+        params = filter_attrs(params || {})
+        params = @params.merge(params) if @params
+        params = self.as_json.merge(params)
+        params = filter_attrs(params)
+
+        response = self.class.request(
+          :put,
+          url: self.url,
+          params: params,
+          headers: headers
+        )
+        json = JSON.parse(response)
+        json = @params.merge(json) if @params
+        json = @attrs.merge(json)  if @attrs
+        init_from(json)
+        self
+      end
+
+    end
+  end
+end

data/lib/essential/version.rb

@@ -0,0 +1,3 @@
+module Essential
+  VERSION = '0.9.0'.freeze
+end

data/test/essential/account_test.rb

@@ -0,0 +1,22 @@
+require 'test_helper'
+
+class AccountTest < EssentialTest
+
+  def test_invalid_credentials
+    error = assert_raises Essential::APIError do
+      Essential::Account.retrieve(headers: {sid: 'sid_nope'})
+    end
+    assert_equal 401, error.http_status
+  end
+
+  def test_valid_credentials
+    account = Essential::Account.retrieve
+
+    prefixed_sid = Essential.sid
+    prefixed_sid = 'ac_' << prefixed_sid unless 0 == prefixed_sid.index('ac_')
+
+    assert_equal prefixed_sid, account.sid
+    assert_equal Essential.token, account.token
+    refute_nil account.name
+  end
+end

data/test/essential/messaging/channel_test.rb

@@ -0,0 +1,62 @@
+require 'test_helper'
+
+class ChannelTest < EssentialTest
+  include Essential::Messaging
+
+  def test_retrieve
+    assert_raises ArgumentError do
+      channel = Channel.retrieve('')
+    end
+
+    assert_raises ArgumentError do
+      Channel.retrieve(nil)
+    end
+
+    channel = Channel.retrieve('ch_p03Gjl8Uzn0RkZSpHXHnrw')
+    assert_equal 'ch_p03Gjl8Uzn0RkZSpHXHnrw', channel.sid
+    refute_nil channel.name
+    refute_nil channel.created_at
+    refute_nil channel.updated_at
+  end
+
+  def test_list
+    channels = Channel.list
+
+    assert channels.size > 1, 'must have more than one channel'
+
+    first = channels[0]
+    last  = channels[-1]
+
+    refute_equal first.sid, last.sid
+  end
+
+  def test_update
+    secondary = Channel.list.find do |ch|
+      ch.name != 'default' && ch.name != ch.name.reverse
+    end
+
+    refute_nil secondary
+    sid = secondary.sid
+    original_name = secondary.name
+
+    refute_equal 'default', secondary.name
+
+    secondary.update(name: secondary.name.reverse)
+    assert_equal sid, secondary.sid
+    refute_equal original_name, secondary.name
+    assert_equal original_name, secondary.name.reverse
+  end
+
+  def test_relations
+    channel = Channel.retrieve('p03Gjl8Uzn0RkZSpHXHnrw')
+    assert_equal Essential::Account.retrieve, channel.account
+
+    subs = channel.subscribers
+    refute_equal 0, subs.count, 'test requires at least one Subscriber'
+    assert subs.all? {|s| Subscriber === s}
+
+    mess = channel.messages
+    refute_equal 0, mess.count, 'test requires at least one Message'
+    assert mess.all? {|m| Message === m}
+  end
+end

data/test/essential/messaging/message_test.rb

@@ -0,0 +1,119 @@
+require 'test_helper'
+
+class MessageTest < EssentialTest
+  include Essential::Messaging
+
+  def setup
+    @channel = Channel.list.first
+    assert_equal 'default', @channel.name, 'default channel must exist'
+    @subscriber = @channel.subscribers.first
+    @transport = Transport.retrieve(@subscriber.transport_sid)
+  end
+
+  def test_create
+    required = [
+      {body: 'a body', subscriber: @subscriber.sid},
+      {body: 'a body', subscriber: @subscriber.phone_number}
+    ]
+
+    optional = [
+      {},
+      {transport: @transport.sid},
+      {transport: @transport.endpoint},
+      {channel:   @channel.sid},
+      {channel:   @channel.name},
+    ]
+
+    required.each do |req|
+      optional.each do |opt|
+        assert_valid_message Message.create(req.merge(opt))
+      end
+    end
+
+  end
+
+  def test_create_errors
+    map_of_brokenness = {
+      nil => [:body, :subscriber],
+
+      {} => [:body, :subscriber],
+
+      { body: 'haha'} => [:subscriber],
+
+      { body: 'haha', subscriber: 'not_a_sid'} => [:subscriber],
+
+      { body: 'haha',
+        subscriber: 'not_a_phone_number' } => [:subscriber],
+
+      { body: 'haha',
+        subscriber: @subscriber.sid,
+        transport: 'not_a_sid' } => [:transport],
+
+      { body: 'haha',
+        subscriber: @subscriber.sid,
+        transport: 'not_a_transport' } => [:transport],
+
+      { body: 'haha',
+        subscriber: @subscriber.sid,
+        channel: 'not_a_sid' } => [:channel],
+
+      { body: 'haha',
+        subscriber_sid: @subscriber.sid,
+        channel: 'olives' } => [:channel],
+    }
+
+    map_of_brokenness.each do |params, errors|
+      assert_error_with_params *errors do
+        Message.create(params)
+      end
+    end
+  end
+
+  def test_create_via_aliases
+    assert_valid_message Message.create(
+                           subscriber: @subscriber.phone_number,
+                           body: 'addressed to @subscriber.phone_number'
+                         )
+
+    assert_valid_message Message.create(
+                           subscriber: @subscriber.sid,
+                           transport: @transport.endpoint,
+                           body: 'sent via @transport.endpoint'
+                         )
+
+    assert_valid_message Message.create(
+                           subscriber: @subscriber.phone_number,
+                           channel: @channel.name,
+                           body: 'sent via @channel.name'
+                         )
+  end
+
+  def test_create_new_subscriber
+    next_phone = @channel.subscribers.map(&:phone_number).sort.last.to_i + 1
+
+    m = Message.create(
+      subscriber: format('%d', next_phone),
+      body: format('a message for %d', next_phone)
+    )
+
+    refute_equal m.subscriber_sid, @subscriber.sid, 'subscriber_sid must match'
+    assert_equal m.transport_sid, @transport.sid, 'transport_sid must match'
+    assert_equal m.channel_sid, @channel.sid, 'channel_sid must match'
+  end
+
+  def test_relations
+    message = @subscriber.messages.last
+
+    assert_equal @channel,    message.channel
+    assert_equal @subscriber, message.subscriber
+    assert_equal @transport,  message.transport
+  end
+
+  protected
+
+  def assert_valid_message(message)
+    assert_equal message.subscriber_sid, @subscriber.sid, 'subscriber_sid must match'
+    assert_equal message.transport_sid, @transport.sid, 'transport_sid must match'
+    assert_equal message.channel_sid, @channel.sid, 'channel_sid must match'
+  end
+end

data/test/essential/messaging/property_test.rb

@@ -0,0 +1,27 @@
+require 'test_helper'
+
+class PropertyTest < EssentialTest
+  def setup
+    channel = Essential::Messaging::Channel.list.first
+    @sub_a = channel.subscribers.create(phone_number: '2221110000')
+    @sub_b = channel.subscribers.create(phone_number: '2221110001')
+    refute_equal @sub_a, @sub_b, 'test requires at least two subscribers'
+  end
+
+  def test_set_props
+    props_a = @sub_a.properties
+    existing_names = Set.new(props_a.map(&:name))
+
+    five_new = (5.times).map do
+      props_a.create(name: SecureRandom.uuid, value: SecureRandom.uuid)
+    end
+
+    new_names = Set.new(five_new.map(&:name))
+
+    assert (existing_names & new_names).empty?, 'new_names must be new'
+
+    props_a.refresh
+    existing_names = Set.new(props_a.map(&:name))
+    assert_equal (existing_names & new_names), new_names, 'must contain all new_names'
+  end
+end

data/test/essential/messaging/subscriber_test.rb

@@ -0,0 +1,106 @@
+require 'test_helper'
+
+class SubscriberTest < EssentialTest
+  include Essential::Messaging
+
+  def setup
+    @channel = Channel.list.first
+  end
+
+  def test_create
+    sub = Subscriber.create(
+      phone_number: '1002003000',
+      channel: @channel.name
+    )
+
+    assert_equal '1002003000', sub.phone_number
+    assert_equal @channel.sid, sub.channel_sid
+  end
+
+  def test_list
+    (1..4).each do |n|
+      Subscriber.create(phone_number: format('100200300%d', n))
+    end
+
+    subs = Subscriber.list
+    assert subs.size > 4, 'should have more than 4 subscribers'
+
+    sub_sids = Set.new(subs.map(&:sid))
+    assert_equal subs.size, sub_sids.size, 'must contain N unique sids'
+  end
+
+  def test_list_bad_channel_sid
+    error = assert_raises Essential::APIError do
+      Subscriber.list(params: {channel: :not_a_real_sid})
+    end
+
+    assert_equal 400, error.http_status
+    refute_nil error.params
+    assert error.params.key?('channel'), 'must complain about channel_sid'
+  end
+
+  def test_list_bad_channel_name
+    error = assert_raises Essential::APIError do
+      Subscriber.list(params: {channel: :not_a_real_name})
+    end
+
+    assert_equal 400, error.http_status
+    refute_nil error.params
+    assert error.params.key?('channel'), 'must complain about channel_name'
+  end
+
+  def test_update
+    sub = Subscriber.create(
+      phone_number: '9998887777',
+      channel: @channel.name
+    )
+    sid = sub.sid.dup
+
+    sub.update(phone_number: '7778889999')
+    assert_equal sid, sub.sid
+    assert_equal '7778889999', sub.phone_number
+
+    sub = Subscriber.retrieve(sid)
+    assert_equal sid, sub.sid
+    assert_equal '7778889999', sub.phone_number
+
+    error = assert_raises Essential::APIError do
+      duplicate = Subscriber.create(
+        phone_number: '1012023333',
+        channel: @channel.sid
+      )
+      duplicate.update(phone_number: sub.phone_number)
+    end
+    assert_equal 400, error.http_status
+    refute_nil error.params
+    assert error.params.key?('phone_number')
+
+    # change it back: if we're running a smoke test, these are
+    # unique and we need to make sure that '7778889999' doesn't
+    # exist at the start of the next run!
+    sub.update(phone_number: '9998887777')
+    assert_equal '9998887777', sub.phone_number
+  end
+
+  def test_unsubscribe
+    sub = Subscriber.create(
+      phone_number: '1002003000',
+      channel: @channel.name
+    )
+
+    response = sub.unsubscribe
+
+    Subscriber.retrieve(sub.sid)
+  end
+
+  def test_relations
+    sub = @channel.subscribers.first
+
+    assert_equal @channel, sub.channel
+    assert_equal sub.transport_sid, sub.transport.sid
+
+    mess = sub.messages
+    refute_equal 0, mess.count
+    assert mess.all? {|m| Message === m}
+  end
+end