ringcentral_sdk 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: df84f0ee4eab215d88476494ab7ff4681c59fe34
-  data.tar.gz: 0bcb1c96920506ee4d63d4a162c9cab33a25078d
+  metadata.gz: 1f9dcd84f1f05d75c88713e2670ef117ff10fbbc
+  data.tar.gz: 592200667132fc64debd755707acb7b89e820926
 SHA512:
-  metadata.gz: 89675600de9040918b4fead9d4134d00d2107ff4501e81108189126452201a6c2b7d1130e9a92921dfe744f39fd84b190c25cc6a34ceec65758649f63d2d1733
-  data.tar.gz: d64154488b9a64cdf2385112b1a2b548a6092f15c57b1550eecdbae005b19f080343108f917d07ff281603d44468cc7d4a3dad211b85b3966286e78e433036fa
+  metadata.gz: fdb5b49fd8ee320bf2309e976a106f4d721251e5b355b523c358394e6341ea50e6f8e5b869b40988efff9bba687a1b3a66860c132eaa782f7c5c2631a021a2f3
+  data.tar.gz: 0d84fb441b6be1b14fd92c6a164856ec3b80a6762c822bf8dad71adc7c8e5207f463124b40997d78f9ddf0704eaee17dfdc25d2ac1ac2645489e1b917031d5df

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 CHANGELOG
 ---------
+- **2015-10-18**: 0.5.0
+  - Add stubbed tests via `mocha`
+  - Add `RingCentralSdk.new()` sugar method
+  - Modify `RingCentralSdk::RC_SERVER_PRODUCTION` url from `RingCentralSdk::Sdk::RC_SERVER_Production`
+  - Remove `lib/ringcentral_sdk/sdk.rb` file and `RingCentralSdk::Sdk` class
+  - Remove `lib/ringcentral_sdk/version.rb` file
+  - Remove `VERSION.txt` file
 - **2015-10-15**: 0.4.0
   - Add 3-Legged OAuth support via platform `authorize_url` and `authorize_code` methods
   - Add `oauth2-sinatra` demo app in `scripts` directory

data/Gemfile

@@ -0,0 +1,26 @@
+source ENV['GEM_SOURCE'] || "https://rubygems.org"
+
+gem 'coveralls'
+gem 'faraday', '~> 0.9.0'
+gem 'faraday_middleware'
+gem 'faraday_middleware-oauth2_refresh'
+gem 'logger'
+gem 'mime'
+gem 'mime-types'
+gem 'mocha'
+gem 'multi_json'
+gem 'oauth2'
+gem 'pubnub', '~> 3.7.3'
+gem 'rake'
+gem 'simplecov'
+gem 'test-unit'
+gem 'timers'
+
+# Ruby 1.8.7 is not currently supported
+# platforms :ruby_18 do
+#  gem 'mime-types', '~> 1.25'
+#  gem 'rest-client', '~> 1.6.0'
+#  # gem 'mime-types', '~> 2.5'
+# end
+
+# vim:ft=ruby

data/README.md

@@ -1,12 +1,12 @@
-RingCentral SDK
-===============
+RingCentral SDK for Ruby
+========================
 
 [![Gem Version](https://badge.fury.io/rb/ringcentral_sdk.svg)](http://badge.fury.io/rb/ringcentral_sdk)
 [![Build Status](https://img.shields.io/travis/grokify/ringcentral-sdk-ruby/master.svg)](https://travis-ci.org/grokify/ringcentral-sdk-ruby)
-[![Dependency Status](https://gemnasium.com/bogdanRada/ruby-gem-downloads-badge.svg)](https://gemnasium.com/bogdanRada/ruby-gem-downloads-badge)
+[![Coverage Status](https://coveralls.io/repos/grokify/ringcentral-sdk-ruby/badge.svg?branch=master)](https://coveralls.io/r/grokify/ringcentral-sdk-ruby?branch=master)
+[![Dependency Status](https://gemnasium.com/grokify/ringcentral-sdk-ruby.svg)](https://gemnasium.com/grokify/ringcentral-sdk-ruby)
 [![Code Climate](https://codeclimate.com/github/grokify/ringcentral-sdk-ruby/badges/gpa.svg)](https://codeclimate.com/github/grokify/ringcentral-sdk-ruby)
 [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/grokify/ringcentral-sdk-ruby/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/grokify/ringcentral-sdk-ruby/?branch=master)
-[![Coverage Status](https://coveralls.io/repos/grokify/ringcentral-sdk-ruby/badge.svg?branch=master)](https://coveralls.io/r/grokify/ringcentral-sdk-ruby?branch=master)
 [![Docs](https://img.shields.io/badge/docs-readthedocs-blue.svg)](http://ringcentral-sdk-ruby.readthedocs.org/)
 [![Docs](https://img.shields.io/badge/docs-rubydoc-blue.svg)](http://www.rubydoc.info/gems/ringcentral_sdk/)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/grokify/ringcentral-sdk-ruby/master/LICENSE.txt)
@@ -18,19 +18,22 @@ RingCentral SDK
   2. [To Do](#to-do)
 2. [Documentation](#documentation)
 3. [Installation](#installation)
-2. [Usage](#usage)
+4. [Usage](#usage)
   1. [Instantiation](#instantiation)
   1. [Authorization](#authorization)
     1. [Password Grant](#password-grant)
     1. [Authorization Code Grant](#authorization-code-grant)
   1. [API Requests](#api-requests)
-    1. [SMS Example](#sms-example)
-    2. [Fax Example](#fax-example)
+    1. [Generic HTTP Requests](#generic-http-requests)
+    2. [SMS Example](#sms-example)
+    3. [Fax Example](#fax-example)
   1. [Subscriptions](#subscriptions)
-5. [Change Log](#change-log)
-6. [Links](#links)
-7. [Contributions](#contributions)
-8. [License](#license)
+5. [Supported Ruby Versions](#supported-ruby-versions)
+6. [Versioning](#versioning)
+7. [Change Log](#change-log)
+8. [Links](#links)
+9. [Contributions](#contributions)
+10. [License](#license)
 
 ## Overview
 
@@ -42,17 +45,16 @@ This SDK is an early stage library and subject to breaking changes.
 
 ### Included
 
-* OAuth2 authorization code and password grant flows including token refresh via INTRIDEA `OAuth2::AccessToken`
-* Generic API requests handled via `Faraday` client
-* Subscription support via `Pubnub` with auto-decryption
+* 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/)
 
 ### To Do
 
-The following items are still needed for this SDK. Contributions are most welcome.
-
-* Mock tests
+There are no major to do items at this time.
 
 ## Documentation
 
@@ -100,18 +102,18 @@ This provides a very basic guide to using the SDK. Please use the following reso
 
 The RingCentral server URLs can be populated manually or via the included constants:
 
-* `RingCentralSdk::Sdk::RC_SERVER_PRODUCTION`
-* `RingCentralSdk::Sdk::RC_SERVER_SANDBOX`
+* `RingCentralSdk::RC_SERVER_PRODUCTION`
+* `RingCentralSdk::RC_SERVER_SANDBOX`
 
 ```ruby
 require 'ringcentral_sdk'
 
-rcsdk = RingCentralSdk::Sdk.new(
+# Returns RingCentralSdk::Platform instance
+rcsdk = RingCentralSdk.new(
   'myAppKey',
   'myAppSecret',
-  RingCentralSdk::Sdk::RC_SERVER_SANDBOX
+  RingCentralSdk::RC_SERVER_SANDBOX
 )
-platform = rcsdk.platform
 ```
 
 ### Authorization
@@ -122,29 +124,41 @@ The 2-legged OAuth 2.0 flow using a password grant is designed for server applic
 
 ```ruby
 # Initialize using main phone number and extension number
-platform.authorize('myUsername', 'myExtension', 'myPassword')
+rcsdk.authorize('myUsername', 'myExtension', 'myPassword')
 
 # Initialize using user phone number without extension number
 # Extension defaults to company admin extension
-platform.authorize('myUsername', nil, 'myPassword')
+rcsdk.authorize('myUsername', nil, '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.
 
+Using the default authorization URL:
+
 ```ruby
 # Initialize SDK with OAuth redirect URI
-rcsdk = RingCentralSdk::Sdk.new(
+rcsdk = RingCentralSdk.new(
   'myAppKey',
   'myAppSecret',
-  RingCentralSdk::Sdk::RC_SERVER_SANDBOX,
+  RingCentralSdk::RC_SERVER_SANDBOX,
   {:redirect_uri => 'http://example.com/oauth'}
 )
 # Retrieve OAuth authorize url using default redirect URL
-auth_url = rcsdk.platform.authorize_url()
+auth_url = rcsdk.authorize_url()
+```
+
+Customizing authorize URL:
+
+```ruby
+rcsdk = RingCentralSdk.new(
+  'myAppKey',
+  'myAppSecret',
+  RingCentralSdk::RC_SERVER_SANDBOX
+)
 # Retrieve OAuth authorize url using override redirect URL
-auth_url = rcsdk.platform.authorize_url({
+auth_url = rcsdk.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'
@@ -158,7 +172,7 @@ On your redirect page, you can exchange your authorization code for an access to
 
 ```ruby
 code  = params['code'] # retrieve GET 'code' parameter in Sinatra
-rcsdk.platform.authorize_code(code)
+rcsdk.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).
@@ -170,20 +184,20 @@ The platform class performs token refresh procedure automatically if needed. To
 ```ruby
 # Retrieve and save access token when program is to be stopped
 # `token` is an `OAuth2::AccessToken` object
-token_hash = rcsdk.platform.token.to_hash
+token_hash = rcsdk.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:
 
 ```ruby
 # Reuse token_hash in another SDK instance
-rcsdk2 = RingCentralSdk::Sdk.new(
+rcsdk2 = RingCentralSdk.new(
   'myAppKey',
   'myAppSecret',
-  RingCentralSdk::Sdk::RC_SERVER_SANDBOX
+  RingCentralSdk::RC_SERVER_SANDBOX
 )
 # set_token() accepts a hash or OAuth2::AccessToken object
-rcsdk2.platform.set_token(token_hash)
+rcsdk2.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.
@@ -192,20 +206,33 @@ See [the authorization docs](http://ringcentral-sdk-ruby.readthedocs.org/en/late
 
 ### API Requests
 
-Requests are made using the inclued Faraday client which you can
-retrieve by calling `rcsdk.platform.client` or using it directly.
+API requests can be made via the included `Faraday` client or `RingCentralSdk::Helpers::Request` subclasses. These are described below.
+
+#### Generic HTTP Requests
+
+To make generic API requests, use included `Faraday` client which can be accessed via `rcsdk.client`. The client automatically adds the correct access token to the HTTP request and handles OAuth token refresh using the `OAuth` gem.
 
 ```ruby
-client = rcsdk.platform.client
+client = rcsdk.client
 ```
 
+Faraday request middleware has been loaded for the following:
+
+* `:oauth2_refresh`
+* `:json`
+* `:url_encoded`
+
+Faraday response middleware is loaded for the following:
+
+* `:json`
+
 #### SMS Example
 
 SMS and other requests can be easily sent directly without helpers.
 
 ```ruby
 # SMS Example
-response = client.post do |req|
+response = rcsdk.client.post do |req|
   req.url 'account/~/extension/~/sms'
   req.headers['Content-Type'] = 'application/json'
   req.body = {
@@ -219,7 +246,7 @@ end
 #### Fax Example
 
 Request helpers are subclasses of `RingCentralSdk::Helpers::Request` and provide standard methods
-that can be called by the `.request()` method of the SDK and Platform objects. This enables the
+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.
 
 To create your own request helpers, please take a look at the fax one shown below:
@@ -242,11 +269,10 @@ fax = RingCentralSdk::Helpers::CreateFaxRequest.new(
 )
 
 # sending request via request helper methods
-response = sdk.request(fax)
-response = sdk.platform.request(fax)
+response = rcsdk.request(fax)
 
 # sending request via standard Faraday client
-response = client.post do |req|
+response = rcsdk.client.post do |req|
   req.url fax.url
   req.headers['Content-Type'] = fax.content_type
   req.body = fax.body
@@ -274,6 +300,19 @@ sub.add_observer(MyObserver.new())
 sub.destroy() # end the subscription
 ```
 
+## Supported Ruby Versions
+
+This library supports and is [tested against](https://travis-ci.org/grokify/ringcentral-sdk-ruby) the following Ruby implementations:
+
+* Ruby 2.2.3, 2.2.0
+* Ruby 2.1.7, 2.1.0
+* Ruby 2.0.0
+* Ruby 1.9.3
+* [JRuby](http://jruby.org/)
+* [Rubinius](http://rubini.us/)
+
+Note: Ruby 1.8.7 works except for subscription support which relies on the `pubnub` gem. If there is a need for 1.8.7 support, consider creating a GitHub issue so we can evalute creating a separate library for subscription handling.
+
 ## Versioning
 
 This project is currently in development and the API can change. During initial development (Version 0.x.x), minor version changes will indicate either substantial feature inclusion or breaking changes.

data/lib/ringcentral_sdk.rb

@@ -1,9 +1,18 @@
-require 'ringcentral_sdk/version.rb'
-
 module RingCentralSdk
+
+  VERSION = '0.5.0'
+
+  RC_SERVER_PRODUCTION = 'https://platform.ringcentral.com'
+  RC_SERVER_SANDBOX    = 'https://platform.devtest.ringcentral.com'
+
   autoload :Helpers, 'ringcentral_sdk/helpers'
   autoload :Platform, 'ringcentral_sdk/platform'
-  autoload :PubnubFactory, 'ringcentral_sdk/pubnub_factory'
-  autoload :Sdk, 'ringcentral_sdk/sdk'
   autoload :Subscription, 'ringcentral_sdk/subscription'
+
+  class << self
+    def new(app_key, app_secret, server_url=nil, opts={})
+      RingCentralSdk::Platform.new(app_key, app_secret, server_url, opts)
+    end
+  end
+
 end

data/lib/ringcentral_sdk/helpers/fax.rb

@@ -62,15 +62,14 @@ module RingCentralSdk::Helpers
       @msg.add(text_part)
     end
 
-    def add_file(file_name=nil, content_type=nil, base64_encode=false)
+    def add_file(file_name, content_type=nil, base64_encode=false)
       file_part = get_file_part(file_name, content_type, base64_encode)
 
       @msg.add(file_part)
       return true
     end
 
-    def get_file_part(file_name=nil, content_type=nil, base64_encode=false)
-
+    def get_file_part(file_name, content_type=nil, base64_encode=false)
       file_bytes = get_file_bytes(file_name)
 
       file_part  = base64_encode \
@@ -85,17 +84,17 @@ module RingCentralSdk::Helpers
     end
 
     def get_file_bytes(file_name=nil)
-
       unless File.file?(file_name.to_s)
         raise "File \"#{file_name.to_s}\" does not exist or cannot be read"
       end
 
-      file_bytes = RUBY_VERSION < '1.9' \
-        ? File.open(file_name, 'rb')        { |f| f.read } \
-        : File.open(file_name, 'rb:BINARY') { |f| f.read }
+      # file_bytes = RUBY_VERSION < '1.9' \ # 1.8.7 removed due to subscription
+      #  ? File.open(file_name, 'rb')        { |f| f.read } \
+      #  : File.open(file_name, 'rb:BINARY') { |f| f.read }
 
-      return file_bytes
+      file_bytes = File.open(file_name, 'rb:BINARY') { |f| f.read }
 
+      return file_bytes
     end
 
     def get_file_content_type(file_name=nil, content_type=nil)

data/lib/ringcentral_sdk/platform.rb

@@ -26,15 +26,22 @@ module RingCentralSdk
     attr_reader   :user_agent
     attr_reader   :redirect_uri
 
-    def initialize(app_key='', app_secret='', server_url=RingCentralSdk::Sdk::RC_SERVER_SANDBOX, opts={})
-      @app_key      = app_key
-      @app_secret   = app_secret
+    def initialize(app_key, app_secret, server_url=RingCentralSdk::RC_SERVER_SANDBOX, opts={})
+      @app_key      = app_key.to_s
+      @app_secret   = app_secret.to_s
       @server_url   = server_url
       @token        = nil
       @client       = nil
-      @redirect_uri = opts.has_key?(:redirect_uri) ? opts[:redirect_uri] : ''
+      @redirect_uri = ''
       @user_agent   = get_user_agent()
       @oauth2client = new_oauth2_client()
+      if opts.is_a?(Hash)
+        @redirect_uri = opts.has_key?(:redirect_uri) ? opts[:redirect_uri] : ''
+        if opts.has_key?(:username) && opts.has_key?(:password)
+          extension = opts.has_key?(:extension) ? opts[:extension] : ''
+          authorize_password(opts[:username], extension, opts[:password])
+        end
+      end
     end
 
     def get_api_version_url()
@@ -70,6 +77,17 @@ module RingCentralSdk
       return built_url
     end
 
+    def create_urls(urls, add_server=false, add_method=nil, add_token=false)
+      unless urls.is_a?(Array)
+        raise "URLs is not an array"
+      end
+      built_urls = []
+      urls.each do |url|
+        built_urls.push(create_url(url, add_server, add_method, add_token))
+      end
+      return built_urls
+    end
+
     def authorize_url(opts={})
       if ! opts.has_key?(:redirect_uri) && @redirect_uri.to_s.length>0
         opts[:redirect_uri] = @redirect_uri.to_s
@@ -86,7 +104,7 @@ module RingCentralSdk
       return token
     end
 
-    def authorize_password(username='', extension='', password='', remember=false)
+    def authorize_password(username, extension='', password='', remember=false)
       token = @oauth2client.password.get_token(username, password, {
         :extension => extension,
         :headers   => { 'Authorization' => 'Basic ' + get_api_key() } })
@@ -111,7 +129,7 @@ module RingCentralSdk
         conn.request  :url_encoded
         conn.headers['User-Agent'] = @user_agent
         conn.headers['Rc-User-Agent'] = @user_agent
-        conn.response :json, :content_type => 'application/json'
+        conn.response :json, :content_type => /\bjson$/
         conn.adapter  Faraday.default_adapter
       end
     end
@@ -123,6 +141,16 @@ module RingCentralSdk
         :token_url     => TOKEN_ENDPOINT)
     end
 
+    def set_oauth2_client(client=nil)
+      if client.nil?
+        @oauth2client = new_oauth2_client()
+      elsif client.is_a?(OAuth2::Client)
+        @oauth2client = client
+      else
+        raise "client is not an OAuth2::Client"
+      end
+    end
+
     def get_api_key()
       api_key = (@app_key.is_a?(String) && @app_secret.is_a?(String)) \
         ? Base64.encode64("#{@app_key}:#{@app_secret}").gsub(/[\s\t\r\n]/,'') : ''
@@ -142,7 +170,6 @@ module RingCentralSdk
         end
         return resp
       end
-      return nil
     end
 
     def get_user_agent()
@@ -154,6 +181,10 @@ module RingCentralSdk
       return ua.strip
     end
 
+    def create_subscription()
+      return RingCentralSdk::Subscription.new(self)
+    end
+
     alias_method :authorize, :authorize_password
     alias_method :login, :authorize_password
     private :get_api_version_url