ringcentral_sdk 0.5.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 96b95c556e178ef01ddbc722d0c3218957847cb0
-  data.tar.gz: 265aa9e0b869a20fd04a137e96639eb33ef63366
+  metadata.gz: df5aca1bce66925c5e3e14d134fba3f5b53625e9
+  data.tar.gz: 811bac728f717e58b0ab0f7c5c1b420468103c3f
 SHA512:
-  metadata.gz: f4beda03bae9a21852650aea069973125272e0f9872450868588be2656ea3fc63129e0eb881191682c58db92715ac901cb858e2b96e014dd34d66738731491a4
-  data.tar.gz: 2841f8cd41b0db6df6fa5fd42a8faf7e83dafe3d35bf797c449fe456e5696b5fc0a02389f6f7eacbd87f9067187dccbf8fc593f82535a8df8012f025dd293ebf
+  metadata.gz: 99e6878c0e06d67cd959eabad0ae6291714f7d11e9ab00f8d22de5fcd72f873ccbca7001f0b4fd097c1899c2c6f04be1f2b7edcac6129e9d8d049fa751ec7763
+  data.tar.gz: 2878c4c401b37fbe11c2ca7b7a3066bedcc5f62542f8de8dfb1071070608d0deea9b131f580ec8b2dd19f43d644ffa8c788e98031afba5832fa43a0f86b012a6

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 CHANGELOG
 ---------
+- **2016-01-23**: 0.9.0
+  - Major refactor
+  - Add `RingCentral::REST::Config` and dotenv support
+- **2016-01-22**: 0.5.2
+  - Add `RingCentralSdk::Cache::Extensions`
+  - Add `RingCentralSdk::Helpers::ExtensionPresence`
+  - Add Call Queue Member Status mydocs documentation
 - **2015-12-08**: 0.5.1
   - Add call recording transcription demo script via VoiceBase
   - Fix PubNub unsubscribe bug

data/Gemfile

@@ -1,12 +1,14 @@
-source ENV['GEM_SOURCE'] || "https://rubygems.org"
+source ENV['GEM_SOURCE'] || 'https://rubygems.org'
 
 gem 'coveralls'
+gem 'dotenv'
 gem 'faraday', '~> 0.9.0'
 gem 'faraday_middleware'
 gem 'faraday_middleware-oauth2_refresh'
 gem 'logger'
 gem 'mime'
 gem 'mime-types'
+gem 'mime_builder'
 gem 'mocha'
 gem 'multi_json'
 gem 'oauth2'

data/Gemfile.lock

@@ -0,0 +1,96 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coveralls (0.8.10)
+      json (~> 1.8)
+      rest-client (>= 1.6.8, < 2)
+      simplecov (~> 0.11.0)
+      term-ansicolor (~> 1.3)
+      thor (~> 0.19.1)
+      tins (~> 1.6.0)
+    docile (1.1.5)
+    domain_name (0.5.25)
+      unf (>= 0.0.5, < 1.0.0)
+    dotenv (2.1.0)
+    eventmachine (1.0.9.1)
+    faraday (0.9.2)
+      multipart-post (>= 1.2, < 3)
+    faraday_middleware (0.10.0)
+      faraday (>= 0.7.4, < 0.10)
+    faraday_middleware-oauth2_refresh (0.0.2)
+      faraday (~> 0.9, >= 0.9)
+      faraday_middleware (~> 0, >= 0)
+    hitimes (1.2.3)
+    http-cookie (1.0.2)
+      domain_name (~> 0.5)
+    json (1.8.3)
+    jwt (1.5.2)
+    logger (1.2.8)
+    metaclass (0.0.4)
+    mime (0.4.3)
+    mime-types (2.99)
+    mime_builder (0.0.2)
+      mime
+      mime-types (>= 1.25)
+    mocha (1.1.0)
+      metaclass (~> 0.0.1)
+    multi_json (1.11.2)
+    multi_xml (0.5.5)
+    multipart-post (2.0.0)
+    net-http-persistent (2.9.4)
+    netrc (0.11.0)
+    oauth2 (1.0.0)
+      faraday (>= 0.8, < 0.10)
+      jwt (~> 1.0)
+      multi_json (~> 1.3)
+      multi_xml (~> 0.5)
+      rack (~> 1.2)
+    power_assert (0.2.7)
+    pubnub (3.7.10)
+      eventmachine (~> 1.0)
+      json (~> 1.8)
+      net-http-persistent (~> 2.9)
+    rack (1.6.4)
+    rake (10.5.0)
+    rest-client (1.8.0)
+      http-cookie (>= 1.0.2, < 2.0)
+      mime-types (>= 1.16, < 3.0)
+      netrc (~> 0.7)
+    simplecov (0.11.1)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    term-ansicolor (1.3.2)
+      tins (~> 1.0)
+    test-unit (3.1.7)
+      power_assert
+    thor (0.19.1)
+    timers (4.1.1)
+      hitimes
+    tins (1.6.0)
+    unf (0.1.4)
+      unf_ext
+    unf_ext (0.0.7.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  coveralls
+  dotenv
+  faraday (~> 0.9.0)
+  faraday_middleware
+  faraday_middleware-oauth2_refresh
+  logger
+  mime
+  mime-types
+  mime_builder
+  mocha
+  multi_json
+  oauth2
+  pubnub (~> 3.7.3)
+  rake
+  simplecov
+  test-unit
+  timers

data/README.md

@@ -15,7 +15,6 @@ RingCentral SDK for Ruby
 ## Table of contents
 
 1. [Overview](#overview)
-  1. [Included](#included)
 2. [Documentation](#documentation)
 3. [Installation](#installation)
 4. [Usage](#usage)
@@ -37,16 +36,7 @@ RingCentral SDK for Ruby
 
 ## Overview
 
-A gem for using the [RingCentral REST API](https://developers.ringcentral.com). [Click here to read the full documentation](http://ringcentral-sdk-ruby.readthedocs.org/)
-
-### Included
-
-* Authorization via `OAuth2` with authorization code and password grant flows including token refresh
-* Generic API requests via `Faraday` client
-* Subscriptions via `Pubnub` with auto-decryption
-* Fax request helper to create `multipart/mixed` messages
-* Unit test suite via `Test::Unit` and `mocha`
-* Docs via [Read the Docs](http://ringcentral-sdk-ruby.readthedocs.org/) and [RubyDoc](http://www.rubydoc.info/gems/ringcentral_sdk/)
+A library for using the [RingCentral REST API](https://developers.ringcentral.com). [Click here to read the full documentation](http://ringcentral-sdk-ruby.readthedocs.org/).
 
 ## Documentation
 
@@ -89,106 +79,78 @@ This provides a very basic guide to using the SDK. Please use the following reso
 2. [SDK Reference](http://www.rubydoc.info/gems/ringcentral_sdk/). 
 1. [API Developer and Reference Guide](https://developers.ringcentral.com/api-docs/latest/index.html)
 
-### Instantiation
+### Instantiation and Authorization
+
+How you instantiate the SDK can depend on whether you use OAuth 2.0 password grant or the authorization code grant which are both described here.
 
-The RingCentral server URLs can be populated manually or via the included constants:
+It is also necessary to specify your RingCentral API end point URL which are included constants:
 
 * `RingCentralSdk::RC_SERVER_PRODUCTION`
 * `RingCentralSdk::RC_SERVER_SANDBOX`
 
+#### Password Grant
+
+The OAuth 2.0 resource owner password grant flow is designed for server applications where the app and resource owners are the same.
+
 ```ruby
 require 'ringcentral_sdk'
 
 # Returns RingCentralSdk::Platform instance
-rcsdk = RingCentralSdk.new(
+client = RingCentralSdk::REST::Client.new(
   'myAppKey',
   'myAppSecret',
   RingCentralSdk::RC_SERVER_SANDBOX
 )
-```
-
-### Authorization
-
-#### Password Grant
 
-The 2-legged OAuth 2.0 flow using a password grant is designed for server applications where the app and resource owners are the same.
-
-```ruby
-# Initialize using main phone number and extension number
-rcsdk.authorize('myUsername', 'myExtension', 'myPassword')
-
-# Initialize using user phone number without extension number
-# Extension defaults to company admin extension
-rcsdk.authorize('myUsername', nil, 'myPassword')
+# extension will default to company admin extension if not provided
+client.authorize_password('myUsername', 'myExtension', 'myPassword')
 ```
 
 #### Authorization Code Grant
 
-The 3-legged OAuth 2.0 flow using an authorization code grant is designed for web apps and public apps where authorization needs to be granted by a 3rd party resource owner.
+The OAuth 2.0 authorization code grant is designed for where authorization needs to be granted by a 3rd party resource owner.
 
 Using the default authorization URL:
 
 ```ruby
 # Initialize SDK with OAuth redirect URI
-rcsdk = RingCentralSdk.new(
+client = RingCentralSdk::REST::Client.new(
   'myAppKey',
   'myAppSecret',
   RingCentralSdk::RC_SERVER_SANDBOX,
   {:redirect_uri => 'http://example.com/oauth'}
 )
-# Retrieve OAuth authorize url using default redirect URL
-auth_url = rcsdk.authorize_url()
-```
 
-Customizing authorize URL:
-
-```ruby
-rcapi = RingCentralSdk.new(
-  'myAppKey',
-  'myAppSecret',
-  RingCentralSdk::RC_SERVER_SANDBOX
-)
-# Retrieve OAuth authorize url using override redirect URL
-auth_url = rcapi.authorize_url({
-  :redirect_uri => 'my_registered_oauth_url', # optional override of default URL
-  :display      => '', # optional: page|popup|touch|mobile, default 'page'
-  :prompt       => '', # optional: sso|login|consent, default is 'login sso consent'
-  :state        => '', # optional
-  :brand_id     => ''  # optional: string|number
-})
-# Open browser window to authorization url and retrieve authorize code from redirect uri.
+# Retrieve OAuth authorize url using default redirect URL
+auth_url = client.authorize_url()
 ```
 
 On your redirect page, you can exchange your authorization code for an access token using the following:
 
 ```ruby
-code  = params['code'] # retrieve GET 'code' parameter in Sinatra
-rcapi.authorize_code(code)
+code  = params['code'] # e.g. using Sinatra to retrieve code param in Redirect URI
+client.authorize_code(code)
 ```
 
-For a complete working example, a demo Sinatra app is available in the scripts directory at [scripts/oauth2-sinatra](scripts/oauth2-sinatra).
+More information on the authorization code flow:
+
+1. [Full documentation](http://ringcentral-sdk-ruby.readthedocs.org/en/latest/usage/authorization/Authorization/#authorization-code-grant)
+2. [Sinatra example](scripts/oauth2-sinatra)
 
-#### Authentication Lifecycle
+#### Token Reuse
 
 The platform class performs token refresh procedure automatically if needed. To save the access and refresh tokens between instances of the SDK, you can save and reuse the token as follows:
 
 ```ruby
-# Retrieve and save access token when program is to be stopped
-# `token` is an `OAuth2::AccessToken` object
-token_hash = rcsdk.token.to_hash
+# Access `OAuth2::AccessToken` object as hash
+token_hash = client.token.to_hash
 ```
 
-After you have saved the token hash, e.g. as JSON, you can reload it in another instance of the SDK as follows:
+You can reload the token hash in another instance of the SDK as follows:
 
 ```ruby
-# Reuse token_hash in another SDK instance
-rcapi2 = RingCentralSdk.new(
-  'myAppKey',
-  'myAppSecret',
-  RingCentralSdk::RC_SERVER_SANDBOX
-)
 # set_token() accepts a hash or OAuth2::AccessToken object
-rcapi2.set_token(token_hash)
+client.set_token(token_hash)
 ```
 
 Important! You have to manually maintain synchronization of SDK's between requests if you share authentication. When two simultaneous requests will perform refresh, only one will succeed. One of the solutions would be to have semaphor and pause other pending requests while one of them is performing refresh.
@@ -201,16 +163,18 @@ API requests can be made via the included `Faraday` client or `RingCentralSdk::H
 
 #### Generic HTTP Requests
 
-To make generic API requests, use included `Faraday` client which can be accessed via `rcapi.client`. The client automatically adds the correct access token to the HTTP request and handles OAuth token refresh using the `OAuth` gem.
+To make generic API requests, use included `Faraday` client which can be accessed via `client.http`. The client automatically adds the correct access token to the HTTP request and handles OAuth token refresh using the `OAuth` gem.
+
+This is useful to access many API endpoints which do not have custom wrappers and for debugging purposes.
 
 ```ruby
-client = rcapi.client
+http = client.http
 ```
 
 #### SMS Example
 
 ```ruby
-rcapi.messages.create(
+client.messages.sms.create(
   :from => '+16505551212',
   :to => '+14155551212',
   :text => 'Hi there!'
@@ -219,38 +183,48 @@ rcapi.messages.create(
 
 #### Fax Example
 
-Request helpers are subclasses of `RingCentralSdk::Helpers::Request` and provide standard methods
-that can be called by the `.request()` method of the Platform object. This enables the
-requisite information for Faraday to be generated in a standard way.
+Fax files:
 
-To create your own request helpers, please take a look at the fax one shown below:
+```ruby
+client.messages.fax.create(
+  :to => '+14155551212',
+  :coverPageText => 'Hi there!',
+  :files => ['/path/to/myfile.pdf']
+)
+```
 
-The fax helper is included to help create the `multipart/mixed` HTTP request. This consists of
-instantiating a fax helper object and then executing a Faraday POST request. The helper can then
-be used with the standard faraday client or helper `.request()` method that takes the request
-helper object in its entirety.
+Fax text:
 
 ```ruby
-# Fax example using request helper
-fax = RingCentralSdk::Helpers::CreateFaxRequest.new(
-  nil, # auto-inflates to [{:account_id => '~', :extension_id => '~'}]
-  {
-    # phone numbers are in E.164 format with or without leading '+'
-    :to            => [{ :phoneNumber => '+16505551212' }],
-    :coverPageText => 'RingCentral fax PDF demo using Ruby!'
-  },
-  :file_name     => '/path/to/my_file.pdf'
+client.messages.fax.create(
+  :to => '+14155551212',
+  :coverPageText => 'Hi there!',
+  :text => 'Hi there!'
 )
+```
 
-# sending request via request helper methods
-response = rcapi.request(fax)
+#### Subscription Example
 
-# sending request via standard Faraday client
-response = rcapi.client.post do |req|
-  req.url fax.url
-  req.headers['Content-Type'] = fax.content_type
-  req.body = fax.body
+To make subscriptions with RingCentral, use the SDK object to create subscription Observer object and then add observers to it.
+
+```ruby
+# Create an observer object
+class MyObserver
+  def update(message)
+    puts "Subscription Message Received"
+    puts JSON.dump(message)
+  end
 end
+
+# Create an observable subscription and add your observer
+sub = client.create_subscription()
+sub.add_observer(MyObserver.new())
+
+# Subscribe to an arbitrary number of event filters
+sub.subscribe(['/restapi/v1.0/account/~/extension/~/presence'])
+
+# End the subscription
+sub.destroy()
 ```
 
 ## Supported Ruby Versions

data/Rakefile

@@ -14,6 +14,6 @@ end
 desc 'Generate YARD documentation.'
 task :gendoc do
   # puts 'yard doc generation disabled until JRuby build native extensions for redcarpet or yard removes the dependency.'
-  system "yardoc"
-  system "yard stats --list-undoc"
-end
+  system 'yardoc'
+  system 'yard stats --list-undoc'
+end

data/lib/ringcentral_sdk/{cache → rest/cache}/extensions.rb

@@ -1,17 +1,17 @@
 require 'time'
 require 'uri'
 
-module RingCentralSdk::Cache
+module RingCentralSdk::REST::Cache
   class Extensions
 
-    attr_accessor :rc_api
+    attr_accessor :client
     attr_accessor :account_id
     attr_reader :extensions_hash
     attr_reader :extensions_num2id
     attr_reader :last_retrieved
 
-    def initialize(rc_api)
-      @rc_api = rc_api
+    def initialize(client)
+      @client = client
       @account_id = '~'
       @extensions_hash = {}
       @extensions_num2id = {}
@@ -24,7 +24,7 @@ module RingCentralSdk::Cache
       if params.length > 0 
         uri.query = URI.encode_www_form params
       end
-      res = @rc_api.client.get do |req|
+      res = @client.http.get do |req|
         req.url uri.to_s
         if retrieve_all
           req.params['page'] = 1
@@ -32,17 +32,17 @@ module RingCentralSdk::Cache
         end
       end
       res.body['records'].each do |extension|
-        if extension.has_key?('id') && extension['id']>0
+        if extension.key?('id') && extension['id']>0
           @extensions_hash[extension['id'].to_s] = extension
         end
       end
       if retrieve_all
-        while res.body.has_key?('navigation') && res.body['navigation'].has_key?('nextPage')
+        while res.body.key?('navigation') && res.body['navigation'].key?('nextPage')
           res = rcsdk.client.get do |req|
             req.url res.body['navigation']['nextPage']['uri']
           end
           res.body['records'].each do |record|
-            if extension.has_key?('id') && extension['id'].length>0
+            if extension.key?('id') && extension['id'].length>0
               @extensions_hash[extension['id'].to_s] = extension
             end
           end
@@ -59,8 +59,8 @@ module RingCentralSdk::Cache
     def inflate_num2id()
       num2id = {}
       @extensions_hash.each do |k,v|
-        if v.has_key?('id') && v['id']>0 &&
-          v.has_key?('extensionNumber') && v['extensionNumber'].length>0
+        if v.key?('id') && v['id']>0 &&
+          v.key?('extensionNumber') && v['extensionNumber'].length>0
           num2id[v['extensionNumber']] = v['id'].to_s
         end
       end
@@ -72,7 +72,7 @@ module RingCentralSdk::Cache
       if !extension_id.is_a?(String)
         extension_id = extension_id.to_s
       end
-      if @extensions_hash.has_key?(extension_id)
+      if @extensions_hash.key? extension_id
           return @extensions_hash[extension_id]
       end
       return nil
@@ -82,9 +82,9 @@ module RingCentralSdk::Cache
       if !extension_number.is_a?(String)
         extension_number = extension_number.to_s
       end
-      if @extensions_num2id.has_key?(extension_number)
+      if @extensions_num2id.key?(extension_number)
         extension_id = @extensions_num2id[extension_number]
-        if @extensions_hash.has_key?(extension_id)
+        if @extensions_hash.key?(extension_id)
           return @extensions_hash[extension_id]
         end
       end
@@ -101,17 +101,15 @@ module RingCentralSdk::Cache
 
       members = []
 
-      res = @rc_api.client.get do |req|
+      res = @client.http.get do |req|
         req.url "account/#{account_id}/department/#{department_id}/members"
       end
 
-      if res.body.has_key?('records')
+      if res.body.key? 'records'
         res.body['records'].each do |extension|
-          if extension.has_key?('id')
+          if extension.key? 'id'
             member = get_extension_by_id extension['id']
-            if !member.nil?
-              members.push member
-            end
+            members.push member unless member.nil?
           end
         end
       end

data/lib/ringcentral_sdk/rest/cache.rb

@@ -0,0 +1,3 @@
+module RingCentralSdk::REST::Cache
+  autoload :Extensions, 'ringcentral_sdk/rest/cache/extensions'
+end