telapi 1.0.0

data/lib/telapi/message.rb

@@ -0,0 +1,47 @@
+module Telapi
+  # Wraps TelAPI SMS Message functionality
+  class Message < Resource
+    class << self
+      MAX_BODY_LENGTH = 160
+
+      # Returns a resource collection containing Telapi::Message objects
+      # See http://www.telapi.com/docs/api/rest/sms/list/
+      #
+      # Optional params is a hash containing:
+      # +To+:: mobile phone number
+      # +From+:: TelAPI or mobile phone number
+      # +DateSent+:: date in the following format: YYYY-MM-DD
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def list(optional_params = {})
+        response = Network.get(['SMS', 'Messages'], optional_params)
+        ResourceCollection.new(response, 'sms_messages', self)
+      end
+
+      # Returns a specific Telapi::Message object given its id
+      # See http://www.telapi.com/docs/api/rest/sms/view/
+      def get(id)
+        response = Network.get(['SMS', 'Messages', id])
+        Message.new(response)
+      end
+
+      # Creates an SMS Message, returning a Telapi::Message object
+      # See http://www.telapi.com/docs/api/rest/sms/send/
+      #
+      # Required params:
+      # +to+:: mobile phone number
+      # +from+:: TelAPI or mobile phone number
+      # +body+:: plain text up to 160 characters in length
+      #
+      # Optional params:
+      # +status_callback+:: valid URL
+      def create(to, from, body, status_callback=nil)
+        raise RangeError, "Body must be between 0 and #{MAX_BODY_LENGTH} characters" if body.length>MAX_BODY_LENGTH || body.length==0
+        opts = { :To => to, :From => from, :Body => body, :StatusCallback => status_callback }
+        response = Network.post(['SMS', 'Messages'], opts)
+        Message.new(response)
+      end
+
+    end
+  end
+end

data/lib/telapi/network.rb

@@ -0,0 +1,50 @@
+require 'httparty'
+
+module Telapi
+  # Internal object for network operations; wraps HTTParty
+  module Network #:nodoc:
+    include HTTParty
+
+    class << self
+      def get(path_components=[], query=nil)
+        options = default_options.merge(:query => query)
+        handle_response(HTTParty.get api_uri(path_components), options)
+      end
+
+      def post(path_components=[], body)
+        options = default_options.merge(:body => body)
+        handle_response(HTTParty.post api_uri(path_components), options)
+      end
+
+      def delete(path_components=[])
+        handle_response(HTTParty.delete api_uri(path_components), default_options)
+      end
+
+      # path_components is an array of uri fragments, e.g ['Calls', '1234abc']
+      def api_uri(path_components=[])
+        [ Telapi.config.base_uri, 'Accounts', Telapi.config.account_sid, path_components ].flatten.join('/') + response_format
+      end
+
+      def response_format
+        @api_format ||= '.json'
+      end
+
+      def default_options
+        {
+          :basic_auth => {
+            :username => (Telapi.config.account_sid || raise(InvalidConfiguration, 'account_sid')),
+            :password => (Telapi.config.auth_token  || raise(InvalidConfiguration, 'auth_token'))
+          },
+          :ssl_ca_path => Telapi.config.ssl_ca_path
+        }
+      end
+
+      private
+
+      def handle_response(response)
+        raise Telapi::ApiError.new(response.parsed_response) unless response.success?
+        response
+      end
+    end
+  end
+end

data/lib/telapi/notification.rb

@@ -0,0 +1,29 @@
+module Telapi
+  # Wraps TelAPI Notification functionality
+  class Notification < Resource
+    class << self
+
+      # Returns a resource collection containing Telapi::Notification objects
+      # See http://www.telapi.com/docs/api/rest/notifications/list/
+      #
+      # Also, notifications can be scoped to a call, see Telapi::Call::notifications
+      #
+      # Optional params is a hash containing:
+      # +Log+:: 0 (error), 1 (warning), or 2 (info)
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def list(optional_params = {})
+        response = Network.get(['Notifications'], optional_params)
+        ResourceCollection.new(response, 'notifications', self)
+      end
+
+      # Returns a Telapi::Notification object given its id
+      # See http://www.telapi.com/docs/api/rest/notifications/view/
+      def get(id)
+        response = Network.get(['Notifications', id])
+        Notification.new(response)
+      end
+
+    end
+  end
+end

data/lib/telapi/recording.rb

@@ -0,0 +1,69 @@
+module Telapi
+  # Wraps TelAPI Recording functionality
+  class Recording < Resource
+    class << self
+
+      # Returns a resource collection containing Telapi::Recording objects
+      # See http://www.telapi.com/docs/api/rest/recordings/list/
+      #
+      # Also, recordings can be scoped to a call, see Telapi::Call::recordings
+      #
+      # Optional params is a hash containing:
+      # +DateCreated+:: date in the following format: YYYY-MM-DD
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def list(optional_params = {})
+        response = Network.get(['Recordings'], optional_params)
+        ResourceCollection.new(response, 'recordings', self)
+      end
+
+      # Returns a Telapi::Recording object given its id
+      # See http://www.telapi.com/docs/api/rest/recordings/view/
+      def get(id)
+        response = Network.get(['Recordings', id])
+        Recording.new(response)
+      end
+
+      # Transcribes a recording and returns a Telapi::Transcription object
+      # See http://www.telapi.com/docs/api/rest/transcriptions/transcribe-recording/
+      #
+      # Required params:
+      # +id+:: recording id
+      #
+      # Optional params is a hash containing:
+      # +TranscribeCallback+:: valid URL
+      # +CallbackMethod+:: (POST) or GET
+      # +Quality+:: (auto), silver, gold, or platinum
+      def transcribe(id, optional_params = {})
+        response = Network.post(['Recordings', id, 'Transcriptions'], optional_params)
+        Transcription.new(response)
+      end
+
+      # Returns a resource collection containing Telapi::Transcription objects
+      # See http://www.telapi.com/docs/api/rest/transcriptions/list/
+      #
+      # Required params:
+      # +id+:: recording id
+      #
+      # Optional params is a hash containing:
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def transcriptions(id, optional_params = {})
+        response = Network.get(['Recordings', id, 'Transcriptions'], optional_params)
+        ResourceCollection.new(response, 'transcriptions', Transcription)
+      end
+
+    end
+
+    # See ::transcribe
+    def transcribe(optional_params = {})
+      self.class.transcribe(self.sid, optional_params)
+    end
+
+    # See ::transcriptions
+    def transcriptions(optional_params = {})
+      self.class.transcriptions(self.sid, optional_params)
+    end
+
+  end
+end

data/lib/telapi/resource.rb

@@ -0,0 +1,18 @@
+require 'recursive_open_struct'
+
+module Telapi
+  # Base class provides basic behavior for Telapi domain objects
+  # You don't typically instantiate this class directly
+  class Resource < RecursiveOpenStruct
+    include Network
+
+    def initialize(attributes={})
+      super
+      delete_field('subresource_uris') if respond_to?(:subresource_uris)
+    end
+
+    def attributes
+      marshal_dump
+    end
+  end
+end

data/lib/telapi/resource_collection.rb

@@ -0,0 +1,38 @@
+require 'forwardable'
+
+module Telapi
+  # This class wraps Resource objects and provides Enumerable functionality.
+  #
+  # Note that TelAPI collections are automatically separated into pages of results,
+  # see http://www.telapi.com/docs/api/rest/overview/response/.
+  #
+  # Currently this container class does not automatically handle the retrieving of
+  # a previous/next page of results. However, all of the Resource classes that provide
+  # a +list+ method allow you to specify the current page and size.
+  class ResourceCollection
+    include Enumerable
+    extend Forwardable
+
+    attr_reader :items, :page, :num_pages, :page_size, :total, :start, :end
+
+    def initialize(attributes, collection_node_name, resource_type)
+      @page      = attributes['page']
+      @num_pages = attributes['num_pages']
+      @page_size = attributes['page_size']
+      @total     = attributes['total']
+      @start     = attributes['start']
+      @end       = attributes['end']
+      @items     = []
+
+      attributes[collection_node_name].each do |item|
+        @items << resource_type.send(:new, item)
+      end if attributes[collection_node_name]
+    end
+
+    def_delegators :@items, :[], :empty?, :last
+
+    def each
+      @items.each { |i| yield i }
+    end
+  end
+end

data/lib/telapi/transcription.rb

@@ -0,0 +1,44 @@
+module Telapi
+  # Wraps TelAPI Transcription functionality
+  class Transcription < Resource
+    class << self
+
+      # Returns a resource collection containing Telapi::Transcription objects
+      # See http://www.telapi.com/docs/api/rest/transcriptions/list/
+      #
+      # Also, Transcriptions can be scoped to a recording, see Telapi::Recording::transcriptions
+      #
+      # Optional params is a hash containing:
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def list(optional_params = {})
+        response = Network.get(['Transcriptions'], optional_params)
+        ResourceCollection.new(response, 'transcriptions', self)
+      end
+
+      # Returns a Telapi::Transcription object given its id
+      # See http://www.telapi.com/docs/api/rest/transcriptions/view/
+      def get(id)
+        response = Network.get(['Transcriptions', id])
+        Transcription.new(response)
+      end
+
+      # Transcribes any audio url, returning a Telapi::Transcription object
+      # See http://www.telapi.com/docs/api/rest/transcriptions/transcribe-audio-url/
+      #
+      # Required params:
+      # +audio_url+:: valid url
+      #
+      # Optional params is a hash containing:
+      # +TranscribeCallback+:: valid URL
+      # +CallbackMethod+:: (POST) or GET
+      # +Quality+:: (auto), silver, gold, or platinum
+      def transcribe_audio(audio_url, optional_params = {})
+        opts = { :AudioUrl => audio_url }.merge(optional_params)
+        response = Network.post(['Transcriptions'], opts)
+        Transcription.new(response)
+      end
+
+    end
+  end
+end

data/lib/telapi/version.rb

@@ -0,0 +1,3 @@
+module Telapi
+  VERSION = "1.0.0"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# This file was generated by the `rspec --init` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+
+require 'fakeweb'
+require 'support/telapi_helpers'
+require 'telapi'
+
+FakeWeb.allow_net_connect = false
+
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.include TelapiHelpers
+end

data/spec/support/telapi_helpers.rb

@@ -0,0 +1,38 @@
+module TelapiHelpers #:nodoc:
+  def klass
+    described_class
+  end
+
+  def stub_telapi_request(body = '{"sid": "a1b2c3"}', opts={})
+    options = {:body => body, :content_type => "application/json"}.merge(opts)
+    FakeWeb.register_uri(:any, /.*telapi.com.*/, options)
+  end
+
+  def stub_telapi_request_with_error_response
+    stub_telapi_request(
+      '{"status": 403,
+        "message": "Invalid credentials supplied",
+        "code": 10004,
+        "more_info": "http://www.telapi.com/docs/api/rest/overview/errors/10004"}',
+      :status => 400
+    )
+  end
+
+  def set_account_sid_and_auth_token
+    Telapi.config do |config|
+      config.account_sid = 'a1b2c3'
+      config.auth_token  = 'x5y6z7'
+    end
+  end
+
+  def reset_config
+    Telapi.config do |config|
+      config.account_sid = nil
+      config.auth_token  = nil
+    end
+  end
+
+  def api_should_use(verb_symbol, response={})
+    Telapi::Network.should_receive(verb_symbol).and_return(response)
+  end
+end

data/spec/telapi/account_spec.rb

@@ -0,0 +1,17 @@
+require 'spec_helper'
+
+describe Telapi::Account do
+  before do
+    stub_telapi_request
+    set_account_sid_and_auth_token
+  end
+
+  it { should be_kind_of(Telapi::Resource) }
+
+  describe ".get" do
+    it "calls api via http get and returns an Account resource" do
+      api_should_use(:get)
+      klass.get.should be_a(klass)
+    end
+  end
+end

data/spec/telapi/application_spec.rb

@@ -0,0 +1,69 @@
+require 'spec_helper'
+
+describe Telapi::Application do
+  before do
+    stub_telapi_request
+    set_account_sid_and_auth_token
+  end
+
+  it { should be_kind_of(Telapi::Resource) }
+
+  describe ".list" do
+    before { stub_telapi_request('{ "applications": [] }') }
+
+    it "calls api via http get and returns a ResourceCollection" do
+      api_should_use(:get)
+      klass.list.should be_a(Telapi::ResourceCollection)
+    end
+
+    context "when Applications exist" do
+      before { stub_telapi_request('{ "applications": [{ "friendly_name": "ExampleApplication" }] }') }
+
+      it "has a collection of Application objects" do
+        klass.list.first.should be_a(klass)
+      end
+    end
+  end
+
+  describe ".get" do
+    it "calls api via http get and returns an Application resource" do
+      api_should_use(:get)
+      klass.get('abc123').should be_a(klass)
+    end
+  end
+
+  describe ".create" do
+    it "calls api via http post and returns an Application resource" do
+      api_should_use(:post)
+      klass.create('My App').should be_a(klass)
+    end
+  end
+
+  describe ".update" do
+    it "calls api via http post and returns an Application resource" do
+      api_should_use(:post)
+      klass.update('123', :FriendlyName => 'new name').should be_a(klass)
+    end
+  end
+
+  describe "#update" do
+    it "proxies to Application.update" do
+      klass.should_receive(:update)
+      klass.get('abc123').update(:FriendlyName => 'another name')
+    end
+  end
+
+  describe ".delete" do
+    it "calls api via http delete and returns an Application resource" do
+      api_should_use(:delete)
+      klass.delete('123').should be_a(klass)
+    end
+  end
+
+  describe "#delete" do
+    it "proxies to Application.delete" do
+      klass.should_receive(:delete)
+      klass.get('abc123').delete
+    end
+  end
+end