telapi 1.0.0

data/lib/telapi/caller_id.rb

@@ -0,0 +1,16 @@
+module Telapi
+  # Wraps TelAPI CNAM Caller ID functionality
+  class CallerId < Resource
+    class << self
+
+      # Returns a Telapi::CallerId object given a phone number
+      # See http://www.telapi.com/docs/api/rest/carrier-services/cnam-lookup/
+      def lookup(phone_number)
+        opts = { :PhoneNumber => phone_number }
+        response = Network.get(['CNAM'], opts)
+        CallerId.new(response)
+      end
+
+    end
+  end
+end

data/lib/telapi/carrier.rb

@@ -0,0 +1,16 @@
+module Telapi
+  # Wraps TelAPI Carrier functionality
+  class Carrier < Resource
+    class << self
+
+      # Returns a Telapi::Carrier object given a phone number
+      # See http://www.telapi.com/docs/api/rest/carrier-services/carrier-lookup/
+      def lookup(phone_number)
+        opts = { :PhoneNumber => phone_number }
+        response = Network.get(['Carrier'], opts)
+        Carrier.new(response)
+      end
+
+    end
+  end
+end

data/lib/telapi/conference.rb

@@ -0,0 +1,206 @@
+module Telapi
+  # Wraps TelAPI Conference functionality
+  class Conference < Resource
+    class << self
+
+      # Returns a resource collection containing Telapi::Conference objects
+      # See http://www.telapi.com/docs/api/rest/conferences/list/
+      #
+      # Optional params is a hash containing:
+      # +MemberID+:: string
+      # +Muted+:: true or false
+      # +Deafed+:: true or false
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def list(optional_params = {})
+        response = Network.get(['Conferences'], optional_params)
+        ResourceCollection.new(response, 'conferences', self)
+      end
+
+      # Returns a Telapi::Conference object given its name
+      # See http://www.telapi.com/docs/api/rest/conferences/view/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      #
+      # Optional params is a hash containing:
+      # +MemberID+:: string
+      # +Muted+:: true or (false)
+      # +Deafed+:: true or (false)
+      def get(conference_name, optional_params = {})
+        response = Network.get(['Conferences', conference_name], optional_params)
+        Conference.new(response)
+      end
+
+      # Mute a member of a conference call, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/mute/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      # +member_id+:: string
+      def mute_member(conference_name, member_id)
+        opts = { :MemberID => member_id }
+        response = Network.post(['Conferences', conference_name, 'Mute'], opts)
+        Conference.new(response)
+      end
+
+      # Unmute a member of a conference call, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/unmute/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      # +member_id+:: string
+      def unmute_member(conference_name, member_id)
+        opts = { :MemberID => member_id }
+        response = Network.post(['Conferences', conference_name, 'UnMute'], opts)
+        Conference.new(response)
+      end
+
+      # Deaf audio for a specific member of a conference call, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/deaf/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      # +member_id+:: string
+      def deaf_member(conference_name, member_id)
+        opts = { :MemberID => member_id }
+        response = Network.post(['Conferences', conference_name, 'Deaf'], opts)
+        Conference.new(response)
+      end
+
+      # Restore audio for a specific member of a conference call, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/undeaf/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      # +member_id+:: string
+      def undeaf_member(conference_name, member_id)
+        opts = { :MemberID => member_id }
+        response = Network.post(['Conferences', conference_name, 'UnDeaf'], opts)
+        Conference.new(response)
+      end
+
+      # Hangup a specific member of a conference call, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/hangup/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      # +member_id+:: string
+      def hangup_member(conference_name, member_id)
+        opts = { :MemberID => member_id }
+        response = Network.post(['Conferences', conference_name, 'Hangup'], opts)
+        Conference.new(response)
+      end
+
+      # Remove a specific member of a conference call, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/kick/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      # +member_id+:: string
+      def kick_member(conference_name, member_id)
+        opts = { :MemberID => member_id }
+        response = Network.post(['Conferences', conference_name, 'Kick'], opts)
+        Conference.new(response)
+      end
+
+      # Send message that will be read in an audible voice to conference members, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/speak-text/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      # +member_id+:: string
+      # +text+:: string
+      def speak_text(conference_name, member_id, text)
+        opts = { :MemberID => member_id, :Text => text }
+        response = Network.post(['Conferences', conference_name, 'Say'], opts)
+        Conference.new(response)
+      end
+
+      # Play pre-recorded sound from a file to conference members, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/play-audio/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      # +member_id+:: string
+      # +sound_url+:: valid URL
+      def play_audio(conference_name, member_id, sound_url)
+        opts = { :MemberID => member_id, :Url => sound_url }
+        response = Network.post(['Conferences', conference_name, 'Play'], opts)
+        Conference.new(response)
+      end
+
+      # Record conference, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/start-recording/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      def start_recording(conference_name)
+        response = Network.post(['Conferences', conference_name, 'RecordStart'])
+        Conference.new(response)
+      end
+
+      # End recording of conference, returning a Telapi::Conference object
+      # See http://www.telapi.com/docs/api/rest/conferences/stop-recording/
+      #
+      # Required params:
+      # +conference_name+:: conference name
+      def stop_recording(conference_name)
+        response = Network.post(['Conferences', conference_name, 'RecordStop'])
+        Conference.new(response)
+      end
+
+    end
+
+    # See ::mute_member
+    def mute_member(member_id)
+      self.class.mute_member(self.name, member_id)
+    end
+
+    # See ::unmute_member
+    def unmute_member(member_id)
+      self.class.unmute_member(self.name, member_id)
+    end
+
+    # See ::deaf_member
+    def deaf_member(member_id)
+      self.class.deaf_member(self.name, member_id)
+    end
+
+    # See ::undeaf_member
+    def undeaf_member(member_id)
+      self.class.undeaf_member(self.name, member_id)
+    end
+
+    # See ::hangup_member
+    def hangup_member(member_id)
+      self.class.hangup_member(self.name, member_id)
+    end
+
+    # See ::kick_member
+    def kick_member(member_id)
+      self.class.kick_member(self.name, member_id)
+    end
+
+    # See ::speak_text
+    def speak_text(member_id, text)
+      self.class.speak_text(self.name, member_id, text)
+    end
+
+    # See ::play_audio
+    def play_audio(member_id, sound_url)
+      self.class.play_audio(self.name, member_id, sound_url)
+    end
+
+    # See ::start_recording
+    def start_recording
+      self.class.start_recording(self.name)
+    end
+
+    # See ::stop_recording
+    def stop_recording
+      self.class.stop_recording(self.name)
+    end
+
+  end
+end

data/lib/telapi/configuration.rb

@@ -0,0 +1,40 @@
+require 'ostruct'
+
+module Telapi
+  class Configuration < OpenStruct #:nodoc:
+    def initialize
+      super(
+        :base_uri    => 'https://api.telapi.com/2011-07-01',
+        :ssl_ca_path => '/etc/ssl/certs',
+        :account_sid => nil,
+        :auth_token  => nil
+      )
+    end
+
+    def inspect
+      marshal_dump
+    end
+    alias_method :to_s, :inspect
+  end
+
+  # Change the default Telapi configuration by setting an individual key or passing in a configuration block.
+  #
+  #   # set individual keys
+  #   Telapi.config.ssl_ca_path = '/some/path'
+  #
+  #   # or use a block
+  #   Telapi.config do |config|
+  #     config.ssl_ca_path = '/some/path'
+  #     config.account_sid = 'abc123'
+  #     config.auth_token  = 'xyz567'
+  #   end
+  #
+  # To get the current configuration as a hash:
+  #
+  #   p Telapi.config
+  #   # => {:base_uri=>"https://api.telapi.com/2011-07-01/", :ssl_ca_path=>"/etc/ssl/certs", :account_sid=>"abc123", :auth_token=>"xyz567"}
+  def self.config
+    @config ||= Configuration.new
+    block_given? ? yield(@config) : @config
+  end
+end

data/lib/telapi/error.rb

@@ -0,0 +1,22 @@
+module Telapi
+  class ApiError < StandardError
+    attr_accessor :status, :code, :help_uri
+
+    def initialize(attributes)
+      super attributes['message']
+      @status = attributes['status']
+      @code = attributes['code']
+      @help_uri = attributes['more_info']
+    end
+  end
+
+  class InvalidConfiguration < StandardError
+    def initialize(attribute)
+      @attribute = attribute
+    end
+
+    def message
+      "The following configuration setting is not properly set: #{@attribute}"
+    end
+  end
+end

data/lib/telapi/fraud.rb

@@ -0,0 +1,79 @@
+module Telapi
+  # Wraps TelAPI Fraud control functionality
+  class Fraud < Resource
+    class << self
+
+      # Returns a resource collection containing Telapi::Fraud objects
+      # See http://www.telapi.com/docs/api/rest/fraud-control/list/
+      #
+      # Optional params is a hash containing:
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def list(optional_params = {})
+        response = Network.get(['Fraud'], optional_params)
+        ResourceCollection.new(response, 'frauds', self)
+      end
+
+      # Authorizes destination for outbound calls and sms messages, returns a Telapi::Fraud object
+      # See http://www.telapi.com/docs/api/rest/fraud-control/authorize/
+      #
+      # Required params:
+      # +country_code_iso+:: country code (ISO), see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+      #
+      # Optional params is a hash containing:
+      # +MobileBreakout+:: (true) or false
+      # +LandlineBreakout+:: (true) or false
+      # +SmsEnabled+:: (true) or false
+      def authorize(country_code_iso, optional_params = {})
+        response = Network.post(['Fraud', 'Authorize', country_code_iso], optional_params)
+        Fraud.new(response)
+      end
+
+      # Extend authorized destination for outbound calls and sms messages, returns a Telapi::Fraud object
+      # See http://www.telapi.com/docs/api/rest/fraud-control/extend/
+      #
+      # Required params:
+      # +country_code_iso+:: country code (ISO), see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+      #
+      # Optional params is a hash containing:
+      # +MobileBreakout+:: (true) or false
+      # +LandlineBreakout+:: (true) or false
+      # +SmsEnabled+:: (true) or false
+      def extend_authorization(country_code_iso, optional_params = {})
+        response = Network.post(['Fraud', 'Extend', country_code_iso], optional_params)
+        Fraud.new(response)
+      end
+
+      # Blocks destination for outbound calls and sms messages, returns a Telapi::Fraud object
+      # See http://www.telapi.com/docs/api/rest/fraud-control/block/
+      #
+      # Required params:
+      # +country_code_iso+:: country code (ISO), see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+      #
+      # Optional params is a hash containing:
+      # +MobileBreakout+:: (true) or false
+      # +LandlineBreakout+:: (true) or false
+      # +SmsEnabled+:: (true) or false
+      def block(country_code_iso, optional_params = {})
+        response = Network.post(['Fraud', 'Block', country_code_iso], optional_params)
+        Fraud.new(response)
+      end
+
+      # Whitelist destination for outbound calls and sms messages, returns a Telapi::Fraud object
+      # See http://www.telapi.com/docs/api/rest/fraud-control/whitelist/
+      #
+      # Required params:
+      # +country_code_iso+:: country code (ISO), see http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
+      #
+      # Optional params is a hash containing:
+      # +MobileBreakout+:: (true) or false
+      # +LandlineBreakout+:: (true) or false
+      # +SmsEnabled+:: (true) or false
+      def whitelist(country_code_iso, optional_params = {})
+        response = Network.post(['Fraud', 'Whitelist', country_code_iso], optional_params)
+        Fraud.new(response)
+      end
+
+    end
+  end
+end

data/lib/telapi/inbound_xml.rb

@@ -0,0 +1,36 @@
+require 'nokogiri'
+
+module Telapi
+  # Wraps TelAPI InboundXML functionality
+  # See http://www.telapi.com/docs/api/inboundxml/voice/introduction/
+  class InboundXml
+
+    # Internally Nokogiri builder is being used to construct responses.
+    # See http://nokogiri.org/Nokogiri/XML/Builder.html
+    #
+    # Pass in a block of options:
+    #
+    # Telapi::InboundXml.new do
+    #   Say('Hello.', :loop => 3, :voice => 'man')
+    #   Say('Hello, my name is Jane.', :voice => 'woman')
+    #   Say('Now I will not stop talking.', :loop => 0)
+    # end
+    #
+    # Then calling #response produces the following output:
+    #
+    # <Response>
+    #   <Say loop='3' voice='man'>Hello.</Say>
+    #   <Say voice='woman'>Hello, my name is Jane.</Say>
+    #   <Say loop='0'>Now I will not stop talking.</Say>
+    # </Response>
+    def initialize(&block)
+      @xml = Nokogiri::XML::Builder.new
+      @xml.Response &block
+    end
+
+    # Returns xml
+    def response
+      @xml.to_xml
+    end
+  end
+end

data/lib/telapi/incoming_phone_number.rb

@@ -0,0 +1,86 @@
+module Telapi
+  # Wraps TelAPI Incoming Phone Number functionality
+  class IncomingPhoneNumber < Resource
+    class << self
+
+      # Returns a resource collection containing Telapi::IncomingPhoneNumber objects
+      # See http://www.telapi.com/docs/api/rest/incoming-phone-numbers/list/
+      #
+      # Optional params is a hash containing:
+      # +PhoneNumber+:: valid TelAPI phone number, e.g. 7325551234
+      # +FriendlyName+:: valid domestic format phone number, e.g. 7325551234
+      # +Page+:: integer greater than 0
+      # +PageSize+:: integer greater than 0
+      def list(optional_params = {})
+        response = Network.get(['IncomingPhoneNumbers'], optional_params)
+        ResourceCollection.new(response, 'incoming_phone_numbers', self)
+      end
+
+      # Returns a Telapi::IncomingPhoneNumber object given its id
+      # See http://www.telapi.com/docs/api/rest/incoming-phone-numbers/view/
+      def get(id)
+        response = Network.get(['IncomingPhoneNumbers', id])
+        IncomingPhoneNumber.new(response)
+      end
+
+      # Creates a new incoming phone number, returning a Telapi::IncomingPhoneNumber object
+      # See http://www.telapi.com/docs/api/rest/incoming-phone-numbers/add-or-delete/
+      #
+      # Required params:
+      # +phone_number+:: area code, e.g. 18052585701
+      def create(phone_number)
+        opts = { :PhoneNumber => phone_number }
+        response = Network.post(['IncomingPhoneNumbers'], opts)
+        IncomingPhoneNumber.new(response)
+      end
+
+      # Delete an incoming phone number, returning a Telapi::IncomingPhoneNumber object
+      # See http://www.telapi.com/docs/api/rest/incoming-phone-numbers/add-or-delete/
+      #
+      # Required params:
+      # +id+:: incoming phone number id
+      def delete(id)
+        response = Network.delete(['IncomingPhoneNumbers', id])
+        IncomingPhoneNumber.new(response)
+      end
+
+      # Updates an incoming phone number, returning a Telapi::IncomingPhoneNumber object
+      # See http://www.telapi.com/docs/api/rest/incoming-phone-numbers/update/
+      #
+      # Required params:
+      # +id+:: incoming phone number id
+      #
+      # Optional params is a hash containing:
+      # +FriendlyName+:: string
+      # +VoiceUrl+:: valid URL
+      # +VoiceMethod+:: (POST) or GET
+      # +VoiceFallbackUrl+:: valid URL
+      # +VoiceFallbackMethod+:: (POST) or GET
+      # +VoiceCallerIdLookup+:: true or (false)
+      # +SmsUrl+:: valid URL
+      # +SmsMethod+:: (POST) or GET
+      # +SmsFallbackUrl+:: valid URL
+      # +SmsFallbackMethod+:: (POST) or GET
+      # +HeartbeatUrl+:: valid URL
+      # +HeartbeatMethod+:: (POST) or GET
+      # +StatusCallback+:: valid URL
+      # +StatusCallbackMethod+:: (POST) or GET
+      def update(id, optional_params = {})
+        response = Network.post(['IncomingPhoneNumbers', id], optional_params)
+        IncomingPhoneNumber.new(response)
+      end
+
+    end
+
+    # See ::delete
+    def delete
+      self.class.delete(self.sid)
+    end
+
+    # See ::update
+    def update(optional_params = {})
+      self.class.update(self.sid, optional_params)
+    end
+
+  end
+end