restcomm-ruby 1.2.0

data/docs/faq.rst

@@ -0,0 +1,42 @@
+==========================
+Frequently Asked Questions
+==========================
+
+Hopefully you can find an answer here to one of your questions. If not, please
+contact `help@restcomm.com <mailto:help@restcomm.com>`_.
+
+
+Formatting phone numbers
+------------------------
+
+Restcomm always returns phone numbers that are formatted in the `E.164 format
+<http://en.wikipedia.org/wiki/E.164>`_, like this: ``+12125551234``. However
+your users may enter them like this: ``(212) 555-1234``. This can lead to
+problems when, for example, Restcomm makes a POST request to your server with the
+``From`` phone number as ``+12125551234``, but you stored the phone number in
+your database as ``(212) 555-1234``, causing a database lookup to fail.
+
+We suggest that you convert the number to E.164 format
+before you store it in the database. The `phony
+<https://github.com/floere/phony>`_ gem is excellent
+for this purpose. Install it like this:
+
+.. code-block:: bash
+
+    $ gem install phony
+
+Then you can convert user input to phone numbers like this:
+
+.. code-block:: ruby
+
+    require 'phony'
+
+    def convert_to_e164(raw_phone)
+        Phony.format(
+            raw_phone,
+            format: :international,
+            spaces: ''
+        ).gsub(/\s+/, "") # Phony won't remove all spaces
+    end
+
+    puts convert_to_e164('212 555 1234')   # prints +12125551234

data/docs/getting-started.rst

@@ -0,0 +1,100 @@
+===========
+Quickstart
+===========
+
+Getting started with the Restcomm API couldn't be easier. Create a Restcomm REST
+client to get started. For example, the following code makes a call using the
+Restcomm REST API.
+
+go to the restcomm-ruby/examples/examples.rb files for detailed examples
+
+Make a Call
+===============
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @call = @client.calls.create(
+      to: "9991231234",
+      from: "9991231234",
+      url: "http://twimlets.com/holdmusic?Bucket=com.restcomm.music.ambient"
+    )
+    puts @call.length
+    puts @call.sid
+
+
+Send an SMS
+===========
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    @message = @client.messages.create(
+      to: "+12316851234",
+      from: "+15555555555",
+      body: "Hello there!"
+    )
+
+Send an MMS
+===========
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    @message = @client.messages.create(
+      to: "+15558676309",
+      from: "+15555555555",
+      body: "Jenny I need you!",
+      media_url: "http://restcomm.com/heart.jpg"
+    )
+
+Generating RCML
+=================
+
+To control phone calls, your application needs to output `RCML
+<http://www.restcomm.com/docs/api/twiml/>`_. Use :class:`restcomm.twiml.Response`
+to easily create such responses.
+
+.. code-block:: ruby
+
+    Restcomm::RCML::Response do |r|
+        r.Play "https://api.example-site.com/cowbell.mp3", loop: 5
+    end.text
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="utf-8"?>
+    <Response>
+        <Play loop="5">https://api.example-site.com/cowbell.mp3</Play>
+    <Response>
+
+
+Digging Deeper
+========================
+
+The full power of the Restcomm API is at your fingertips. The :ref:`user-guide`
+explains all the awesome features available to use.
+

data/docs/index.rst

@@ -0,0 +1,109 @@
+=============================
+Restcomm Ruby Helper Library
+=============================
+
+.. _installation:
+
+Installation
+================
+
+Just install the gem!
+
+.. code-block:: bash
+
+    $ gem install restcomm-ruby
+
+Getting Started
+================
+
+The :doc:`/getting-started` will get you up and running in a few quick minutes.
+This guide assumes you understand the core concepts of Restcomm.
+If you've never used Restcomm before, don't fret! Just read
+`about how Restcomm works <http://docs.telestax.com/restcomm-pages/>`_ and then jump in!
+
+
+.. _user-guide:
+
+User Guide
+==================
+
+Functionality is split over three different sub-packages within
+**restcomm-ruby**. Below are in-depth guides to specific portions of the
+library.
+
+
+REST API
+----------
+
+Query the Restcomm REST API to create phone calls, send SMS/MMS messages and more!
+
+.. toctree::
+    :maxdepth: 1
+
+    usage/basics
+    usage/errors
+    usage/messages
+    usage/phone-calls
+    usage/phone-numbers
+    usage/accounts
+    usage/conferences
+    usage/applications
+    usage/notifications
+    usage/recordings
+    usage/transcriptions
+    usage/caller-ids
+    usage/queues
+    usage/sip
+
+RCML
+---------
+
+Generates valid RCML for controlling and manipulating phone calls.
+
+.. toctree::
+    :maxdepth: 2
+
+    usage/twiml
+
+Utilities
+----------
+
+Small functions useful for validating requests are coming from Restcomm
+
+.. toctree::
+    :maxdepth: 1
+
+    usage/validation
+    usage/token-generation
+
+Frequently Asked Questions
+==========================
+
+What to do if you get an ``ImportError``, and some advice about how to format
+phone numbers.
+
+.. toctree::
+    :maxdepth: 2
+
+    faq
+
+Changelog
+=========
+
+See the :doc:`/changelog` for version history.
+
+Support and Development
+==========================
+All development occurs over on
+`Github <https://github.com/Mobicents/restcomm-ruby>`_. To checkout the source,
+
+.. code-block:: bash
+
+    $ git clone git@github.com:Mobicents/restcomm-ruby.git
+
+
+Report bugs using the Github
+`issue tracker <https://github.com/Mobicents/restcomm-ruby/issues>`_.
+
+If you have questions that aren't answered by this documentation,
+ask the `#restcomm IRC channel <irc://irc.freenode.net/#restcomm>`_

data/docs/make.bat

@@ -0,0 +1,170 @@
+@ECHO OFF
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set BUILDDIR=_build
+set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
+if NOT "%PAPER%" == "" (
+	set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
+)
+
+if "%1" == "" goto help
+
+if "%1" == "help" (
+	:help
+	echo.Please use `make ^<target^>` where ^<target^> is one of
+	echo.  html       to make standalone HTML files
+	echo.  dirhtml    to make HTML files named index.html in directories
+	echo.  singlehtml to make a single large HTML file
+	echo.  pickle     to make pickle files
+	echo.  json       to make JSON files
+	echo.  htmlhelp   to make HTML files and a HTML help project
+	echo.  qthelp     to make HTML files and a qthelp project
+	echo.  devhelp    to make HTML files and a Devhelp project
+	echo.  epub       to make an epub
+	echo.  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter
+	echo.  text       to make text files
+	echo.  man        to make manual pages
+	echo.  changes    to make an overview over all changed/added/deprecated items
+	echo.  linkcheck  to check all external links for integrity
+	echo.  doctest    to run all doctests embedded in the documentation if enabled
+	goto end
+)
+
+if "%1" == "clean" (
+	for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
+	del /q /s %BUILDDIR%\*
+	goto end
+)
+
+if "%1" == "html" (
+	%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/html.
+	goto end
+)
+
+if "%1" == "dirhtml" (
+	%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
+	goto end
+)
+
+if "%1" == "singlehtml" (
+	%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
+	goto end
+)
+
+if "%1" == "pickle" (
+	%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the pickle files.
+	goto end
+)
+
+if "%1" == "json" (
+	%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can process the JSON files.
+	goto end
+)
+
+if "%1" == "htmlhelp" (
+	%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run HTML Help Workshop with the ^
+.hhp project file in %BUILDDIR%/htmlhelp.
+	goto end
+)
+
+if "%1" == "qthelp" (
+	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; now you can run "qcollectiongenerator" with the ^
+.qhcp project file in %BUILDDIR%/qthelp, like this:
+	echo.^> qcollectiongenerator %BUILDDIR%\qthelp\restcomm-python2.qhcp
+	echo.To view the help file:
+	echo.^> assistant -collectionFile %BUILDDIR%\qthelp\restcomm-python2.ghc
+	goto end
+)
+
+if "%1" == "devhelp" (
+	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished.
+	goto end
+)
+
+if "%1" == "epub" (
+	%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The epub file is in %BUILDDIR%/epub.
+	goto end
+)
+
+if "%1" == "latex" (
+	%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
+	goto end
+)
+
+if "%1" == "text" (
+	%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The text files are in %BUILDDIR%/text.
+	goto end
+)
+
+if "%1" == "man" (
+	%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Build finished. The manual pages are in %BUILDDIR%/man.
+	goto end
+)
+
+if "%1" == "changes" (
+	%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.The overview file is in %BUILDDIR%/changes.
+	goto end
+)
+
+if "%1" == "linkcheck" (
+	%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Link check complete; look for any errors in the above output ^
+or in %BUILDDIR%/linkcheck/output.txt.
+	goto end
+)
+
+if "%1" == "doctest" (
+	%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
+	if errorlevel 1 exit /b 1
+	echo.
+	echo.Testing of doctests in the sources finished, look at the ^
+results in %BUILDDIR%/doctest/output.txt.
+	goto end
+)
+
+:end

data/docs/src/pip-delete-this-directory.txt

@@ -0,0 +1,5 @@
+This file is placed here by pip to indicate the source was put
+here by pip.
+
+Once this package is successfully installed this source code will be
+deleted (unless you remove this file).

data/docs/usage/accounts.rst

@@ -0,0 +1,96 @@
+.. module:: restcomm.rest
+
+===========
+Accounts
+===========
+
+Managing Restcomm accounts is straightforward.
+Update your own account information or create and manage multiple subaccounts.
+
+For more information, see the
+`Account REST Resource <http://docs.telestax.com/restcomm-pages/>`_
+documentation.
+
+
+Go to the restcomm-ruby/examples/examples.rb for detailed examples of 
+of how to use the restcomm-ruby wrapper
+
+
+Updating Account Information
+----------------------------
+
+Use the :meth:`Account.update` to modify one of your accounts.
+Right now the only valid attribute is :attr:`friendly_name`.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @account = @client.accounts.get(account_sid)
+    @account.update(friendly_name: "My Awesome Account")
+
+
+Creating Subaccounts
+----------------------
+
+Subaccounts are easy to make.
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+    @subaccount = @client.accounts.create(name: "My Awesome SubAccount")
+
+
+Managing Subaccounts
+-------------------------
+
+Say you have a subaccount for Client X with an account sid `AC123`
+
+.. code-block:: ruby
+
+    require 'restcomm-ruby'
+
+    # To find these visit http://docs.telestax.com/restcomm-pages/
+    account_sid = "ACXXXXXXXXXXXXXXXXX"
+    auth_token = "YYYYYYYYYYYYYYYYYY"
+    host = "XXX.XXX.XXX.XXX"
+
+    @client = Restcomm::REST::Client.new account_sid, auth_token, host
+
+    # Client X's subaccount
+    @subaccount = @client.accounts.get('AC123')
+
+Client X hasn't paid you recently, so let's suspend their account.
+
+.. code-block:: ruby
+
+    @subaccount.update(status: 'suspended')
+
+If it was just a misunderstanding, reenable their account.
+
+.. code-block:: ruby
+
+    @subaccount.update(status: 'active')
+
+Otherwise, close their account permanently.
+
+.. code-block:: ruby
+
+    @subaccount.update(status: 'closed')
+
+.. warning::
+    This action can't be undone.
+