ringcentral_sdk 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 53f1dff65956dcafa9e3bd77501e187cf7c67e98
+  data.tar.gz: 8176d3c80e94ff445be20793393d48e6fae8d0f1
+SHA512:
+  metadata.gz: 9e1742a2c45d5c7764a9623f435c674cce3b9f6a4140a2f7c9738a9b43c89ecbb55cdc74a330839ff6de139aca7d4a4db52acfe249e3ac21ef911b6574a44d03
+  data.tar.gz: f8eb9a7e19aeb738fec47dc18af2c5825fe701ff34b8aaf7690258efbd58398ed2f0fcf3604088c511468985f6e299dc27e3b2d4900486ed537a096906d2b206

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+CHANGELOG
+---------
+- **2015-05-14**: 0.0.3
+  - First public release
+- **2015-03-08**: 0.0.2
+  - Convert methods from camelCase to under_scores
+- **2015-03-07**: 0.0.1
+  - Initial release

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2015 John Wang
+ 
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+ 
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+ 
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,194 @@
+RingCentral SDK
+===============
+
+This is an unofficial Ruby SDK for the RingCentral Connect Platform REST API (https://developers.ringcentral.com).
+
+The core SDK objects follow the general design of the [official RingCentral SDKs](https://github.com/ringcentral). The SDK helper additions are included to make it easier to interact with features of the API.
+
+This SDK is an early stage library and subject to breaking changes.
+
+## Included
+
+* OAuth authorization
+* Faraday client with OAuth bearer token handling
+* Fax helper to create multipart/mixed messages
+
+## To Do
+
+The following items are still needed for this SDK. Contributions are most welcome.
+
+* Token refresh
+* Subscriptions
+* Additional tests
+
+Installation
+============
+
+## RubyGems
+
+```sh
+$ gem install ringcentral_sdk
+```
+
+Usage
+=====
+
+## Initialization
+
+The RingCentral server URLs can be populated manually or via the included constants:
+
+* `RingCentralSdk::Sdk::RC_SERVER_PRODUCTION`
+* `RingCentralSdk::Sdk::RC_SERVER_SANDBOX`
+
+```ruby
+## Initialization ##
+
+require 'ringcentral_sdk'
+
+rcsdk = RingCentralSdk::Sdk.new(
+  "myAppKey",
+  "myAppSecret",
+  RingCentralSdk::Sdk::RC_SERVER_SANDBOX
+)
+platform = rcsdk.platform
+```
+
+## Authentication
+
+```ruby
+# Initialize using user phone number without extension number
+
+platform.authorize("myUsername", nil, "myPassword")
+
+# Initialize using main phone number and extension number
+
+platform.authorize("myUsername", "myExtension", "myPassword")
+```
+
+## Creating Requests
+
+Requests are made using the inclued Faraday client.
+
+```ruby
+client = rcsdk.platform.client
+```
+
+## Create SMS Message
+
+SMS and other requests are directly without helpers.
+
+```ruby
+# Send SMS - POST request
+
+response = client.post do |req|
+  req.url 'account/~/extension/~/sms'
+  req.headers['Content-Type'] = 'application/json'
+  req.body = {
+    :from =>   { :phoneNumber => '16505551212' },
+    :to   => [ { :phoneNumber => '14155551212'} ],
+    :text => 'RingCentral SMS demo using Ruby!'
+  }
+end
+```
+
+## Create Fax Message
+
+A fax helper is included that can be used to create the `multipart/mixed` HTTP request.
+
+This consists of instantiating a fax helper object and then executing a Faraday POST request.
+
+```ruby
+# 1) Fax Helper for Text Message
+
+fax = RingCentralSdk::Helpers::CreateFaxRequest.new(
+  { account_id => '~', extension_id => '~' }, # Can be nil or {} for defaults '~'
+  {
+    # phone numbers are in E.164 format with or without leading '+'
+    :to            => [{ :phoneNumber => '+16505551212' }],
+    :faxResolution => 'High',
+    :coverPageText => 'RingCentral fax text demo using Ruby!'
+  },
+  :text => 'RingCentral Fax via Ruby!'
+)
+# send the fax using Faraday below
+
+# 2) Fax Helper for File as Raw Bytes (e.g. PDF or TIFF)
+
+# Sending a file as a plain octet-stream is useful in
+# production as it can decrease file size by 30%.
+
+fax = RingCentralSdk::Helpers::CreateFaxRequest.new(
+  { account_id => '~', extension_id => '~' }, # Can be nil or {} for defaults '~'
+  {
+    # phone numbers are in E.164 format with or without leading '+'
+    :to            => [{ :phoneNumber => '+16505551212' }],
+    :faxResolution => 'High',
+    :coverPageText => 'RingCentral fax PDF demo using Ruby!'
+  },
+  :file_name     => '/path/to/my_file.pdf'
+)
+# send the fax using Faraday below
+
+# 3) Fax Helper for File Base64 Encoded (e.g. PDF or TIFF)
+
+# Sending a file base64 encoded is useful for debugging
+# purposes as the file can be copy and pasted.
+
+fax = RingCentralSdk::Helpers::CreateFaxRequest.new(
+  { account_id => '~', extension_id => '~' }, # Can be nil or {} for defaults '~'
+    {
+    # phone numbers are in E.164 format with or without leading '+'
+    :to            => [{ :phoneNumber => '+16505551212' }],
+    :faxResolution => 'High',
+    :coverPageText => 'RingCentral fax TIFF base64 demo using Ruby!'
+  },
+  :file_name     => '/path/to/my_file.tif',
+  :base64_encode => true
+)
+# send the fax using Faraday below
+
+# Sending the fax
+
+response = client.post do |req|
+  req.url fax.url
+  req.headers['Content-Type'] = fax.content_type
+  req.body = fax.body
+end
+```
+
+Change Log
+==========
+
+- **2015-05-13**: 0.0.3
+  - Initial public release
+
+Links
+=====
+
+Project Repo
+
+* https://github.com/grokify/ringcentral-sdk-ruby
+
+RingCentral API Docs
+
+* https://developers.ringcentral.com/library.html
+
+RingCentral API Explorer
+
+* http://ringcentral.github.io/api-explorer
+
+RingCentral Official SDKs
+
+* https://github.com/ringcentral
+
+Problems, Comments, Suggestions?
+================================
+
+All of the above are most welcome. johncwang@gmail.com
+
+License
+=======
+
+RingCentral SDK is available under an MIT-style license. See {file:LICENSE.txt} for details.
+
+RingCentral SDK © 2015 by John Wang

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rake'
+require 'rake/testtask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the library.'
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/test_*.rb'
+  t.verbose = false
+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

data/VERSION.txt

@@ -0,0 +1 @@
+0.0.3

data/lib/ringcentral_sdk.rb

@@ -0,0 +1,5 @@
+module RingCentralSdk
+  autoload :Helpers, 'ringcentral_sdk/helpers'
+  autoload :Platform, 'ringcentral_sdk/platform'
+  autoload :Sdk, 'ringcentral_sdk/sdk'
+end

data/lib/ringcentral_sdk/helpers.rb

@@ -0,0 +1,3 @@
+module RingCentralSdk::Helpers
+  autoload :CreateFaxRequest, 'ringcentral_sdk/helpers/fax'
+end

data/lib/ringcentral_sdk/helpers/fax.rb

@@ -0,0 +1,130 @@
+require 'base64'
+require 'mime'
+require 'mime-types'
+require 'multi_json'
+
+module RingCentralSdk::Helpers
+  class CreateFaxRequest
+    attr_reader :msg
+
+    def initialize(path_params=nil,metadata=nil,options=nil)
+
+      @msg = MIME::Multipart::Mixed.new
+      @msg.headers.delete('Content-Id')
+
+      @path_params = path_params
+
+      if metadata.is_a?(Hash) || metadata.is_a?(String)
+        add_metadata(metadata)
+      end
+
+      if options.is_a?(Hash)
+        if options.has_key?(:file_name)
+          if options.has_key?(:base64_encode) && options[:base64_encode]
+            add_file_base64(options[:file_name],options[:file_content_type])
+          else
+            add_file_octet_stream(options[:file_name])
+          end
+        elsif options.has_key?(:text)
+          add_file_text(options[:text])
+        end
+      end
+    end
+
+    def add_metadata(json=nil)
+      if json.is_a?(Hash)
+        json = MultiJson.encode(json)
+      end
+      if json.is_a?(String)
+        json_part = MIME::Text.new(json)
+        json_part.headers.delete('Content-Id')
+        json_part.headers.set('Content-Type','application/json')
+        @msg.add(json_part)
+        return true
+      end
+      return false
+    end
+
+    def add_file_text(text=nil,charset='UTF-8')
+      return unless text.is_a?(String)
+      text_part = MIME::Text.new(text,'plain')
+      text_part.headers.delete('Content-Id')
+      @msg.add(text_part)
+    end
+
+    def add_file_base64(file_name=nil,content_type=nil)
+      unless file_name.is_a?(String) && File.file?(file_name)
+        return false
+      end
+
+      content_type = (content_type.is_a?(String) && content_type =~ /^[^\/\s]+\/[^\/\s]+/) \
+        ? content_type : MIME::Types.type_for(file_name).first.content_type
+
+      file_base64 = Base64.encode64(File.binread(file_name))
+
+      base64_part = MIME::Text.new(file_base64)
+      base64_part.headers.delete('Content-Id')
+      base64_part.headers.set('Content-Type',content_type)
+      base64_part.headers.set('Content-Transfer-Encoding','base64')
+
+      @msg.add(base64_part)
+      return true
+    end
+
+    def add_file_octet_stream(file_name=nil)
+      unless file_name.is_a?(String) && File.file?(file_name)
+        return false
+      end
+
+      base_name  = File.basename(file_name)
+      file_bytes = File.binread(file_name)
+
+      file_part  = MIME::Application.new(file_bytes)
+      file_part.headers.delete('Content-Id')
+      file_part.headers.set('Content-Type','application/octet-stream')
+      if base_name.is_a?(String) && base_name.length>0
+        file_part.headers.set('Content-Disposition', "attachment; filename=\"#{base_name}\"")
+      else
+        file_part.headers.set('Content-Disposition', 'attachment')
+      end
+
+      @msg.add(file_part)
+      return true
+    end
+
+    def url()
+      account_id   = "~"
+      extension_id = "~"
+      if @path_params.is_a?(Hash)
+        if @path_params.has?(:account_id) && @path_params[:account_id].length>0
+          account_id = @path_params[:account_id]
+        end
+        if @path_params.has?(:extension_id) && @path_params[:extension_id].length>0
+          account_id = @path_params[:extension_id]
+        end
+      end
+      url = "account/#{account_id}/extension/#{extension_id}/fax"
+      return url
+    end
+
+    def content_type()
+      return @msg.headers.get('Content-Type').to_s
+    end
+
+    def body()
+      return @msg.body.to_s
+    end
+
+    # Experimental
+    def _add_file(file_name=nil)
+      if file_name.is_a?(String) && File.file?(file_name)
+        file_msg = MIME::DiscreteMediaFactory.create(file_name)
+        file_msg.headers.delete('Content-Id')
+        @msg.add(file_msg)
+        return true
+      end
+      return false
+    end
+    private :_add_file
+  end
+end

data/lib/ringcentral_sdk/platform.rb

@@ -0,0 +1,5 @@
+module RingCentralSdk::Platform
+	autoload :Auth, 'ringcentral_sdk/platform/auth'
+	autoload :Parser, 'ringcentral_sdk/platform/parser'
+	autoload :Platform, 'ringcentral_sdk/platform/platform'
+end

data/lib/ringcentral_sdk/platform/auth.rb

@@ -0,0 +1,20 @@
+module RingCentralSdk::Platform
+	class Auth
+		attr_accessor :data
+		attr_accessor :remember
+
+		attr_reader   :access_token
+
+		def initialize()
+			@data     = nil
+			@remember = nil
+		end
+		def set_data(data={})
+			return unless data.is_a?(Hash)
+
+			@access_token = data["access_token"] ? data["access_token"] : ''
+			@token_type   = data["token_type"]   ? data["token_type"]   : ''
+
+		end
+	end
+end

data/lib/ringcentral_sdk/platform/parser.rb

@@ -0,0 +1,5 @@
+module RingCentralSdk::Platform
+	class Parser
+
+	end
+end

data/lib/ringcentral_sdk/platform/platform.rb

@@ -0,0 +1,89 @@
+require 'base64'
+require 'faraday'
+require 'faraday_middleware'
+
+module RingCentralSdk::Platform
+  class Platform
+
+    ACCESS_TOKEN_TTL  = 600             # 10 minutes
+    REFRESH_TOKEN_TTL = 36000           # 10 hours
+    REFRESH_TOKEN_TTL_REMEMBER = 604800 # 1 week
+    ACCOUNT_PREFIX    = '/account/'
+    ACCOUNT_ID        = '~'
+    TOKEN_ENDPOINT    = '/restapi/oauth/token'
+    REVOKE_ENDPOINT   = '/restapi/oauth/revoke'
+    API_VERSION       = 'v1.0'
+    URL_PREFIX        = '/restapi'
+
+    attr_reader :client
+
+    def initialize(app_key='',app_secret='',server_url='https://platform.devtest.ringcentral.com')
+
+      @app_key    = app_key
+      @app_secret = app_secret
+      @server_url = server_url
+      @auth       = RingCentralSdk::Platform::Auth.new
+
+      @client     = Faraday.new(:url => get_api_version_url()) do |conn|
+        conn.request  :json
+        conn.request  :url_encoded
+        conn.response :json, :content_type => 'application/json'
+        conn.adapter  Faraday.default_adapter
+      end
+
+    end
+
+    def get_api_version_url()
+      return @server_url + URL_PREFIX + '/' + API_VERSION 
+    end
+
+    def authorize(username='',extension='',password='',remember=false)
+
+      response = auth_call({}, {
+        :grant_type        => 'password',
+        :username          => username,
+        :extension         => extension.is_a?(String) || extension.is_a?(Integer) ? extension : '',
+        :password          => password,
+        :access_token_ttl  => ACCESS_TOKEN_TTL,
+        :refresh_token_ttl => remember ? REFRESH_TOKEN_TTL_REMEMBER : REFRESH_TOKEN_TTL
+      })
+
+      @auth.set_data( response.body )
+      @auth.remember = remember
+
+      if response.body.has_key?("access_token") && response.body["access_token"].is_a?(String)
+        @client.headers['Authorization'] = 'Bearer ' + response.body["access_token"]
+      end
+
+      return response
+    end
+
+    def get_api_key()
+      if @app_key.is_a?(String) && @app_secret.is_a?(String)
+         return Base64.encode64(@app_key + ":" + @app_secret).gsub(/[\s\r\n]/,"")
+       else
+         return ''
+       end
+    end
+
+    def get_auth_header()
+      if @auth.token_type.is_a?(String) && @auth.access_token.is_a?(String)
+        return @auth.token_type + ' ' + @auth.access_token
+      end
+      return ''
+    end
+
+    def auth_call(queryParams={},body={})
+      return @client.post do |req|
+        req.url TOKEN_ENDPOINT
+        req.headers['Authorization'] = 'Basic ' + get_api_key()
+        req.headers['Content-Type']  = 'application/x-www-form-urlencoded;charset=UTF-8'
+        if body.is_a?(Hash) && body.size > 0
+          req.body = body
+        end
+      end
+    end
+
+    private :auth_call, :get_api_key, :get_api_version_url, :get_auth_header
+  end
+end

data/lib/ringcentral_sdk/sdk.rb

@@ -0,0 +1,15 @@
+module RingCentralSdk
+  class Sdk
+
+    RC_SERVER_PRODUCTION = 'https://platform.ringcentral.com'
+    RC_SERVER_SANDBOX    = 'https://platform.devtest.ringcentral.com'
+
+    attr_reader :parser
+    attr_reader :platform
+
+    def initialize(app_key=nil,app_secret=nil,server_url=nil)
+      @parser   = RingCentralSdk::Platform::Parser.new
+      @platform = RingCentralSdk::Platform::Platform.new(app_key, app_secret, server_url)
+    end
+  end
+end

data/test/test_setup.rb

@@ -0,0 +1,18 @@
+require 'test/unit'
+require 'ringcentral_sdk'
+
+class RingCentralSdkTest < Test::Unit::TestCase
+  def testSetup
+
+    rcsdk = RingCentralSdk::Sdk.new(
+      "myAppKey",
+      "myAppSecret",
+      RingCentralSdk::Sdk::RC_SERVER_SANDBOX
+    )
+
+    assert_equal "RingCentralSdk::Sdk", rcsdk.class.name
+    assert_equal "RingCentralSdk::Platform::Platform", rcsdk.platform.class.name
+    assert_equal "Faraday::Connection", rcsdk.platform.client.class.name
+
+  end
+end

metadata

@@ -0,0 +1,137 @@
+--- !ruby/object:Gem::Specification
+name: ringcentral_sdk
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- John Wang
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-05-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: faraday_middleware
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mime-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description: An unofficial Ruby SDK for the RingCentral Connect Platform API
+email: johncwang@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- VERSION.txt
+- lib/ringcentral_sdk.rb
+- lib/ringcentral_sdk/helpers.rb
+- lib/ringcentral_sdk/helpers/fax.rb
+- lib/ringcentral_sdk/platform.rb
+- lib/ringcentral_sdk/platform/auth.rb
+- lib/ringcentral_sdk/platform/parser.rb
+- lib/ringcentral_sdk/platform/platform.rb
+- lib/ringcentral_sdk/sdk.rb
+- test/test_setup.rb
+homepage: https://github.com/grokify/
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.1
+signing_key: 
+specification_version: 4
+summary: RingCentral SDK - Unofficial Ruby SDK for the RingCentral Connect Platform
+  API
+test_files: []