cpaas-sdk 1.0.0

data/tutorials/GetStarted.md

@@ -0,0 +1,86 @@
+# Get Started
+
+In this quickstart, we will help you dip your toes in before you dive in. This guide will help you get started with the $KANDY$ Ruby SDK.
+
+## Using the SDK
+
+To begin, you will need to install the ruby library in your application. The library can be installed by using the following ways:
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'cpaas-ruby'
+```
+
+And then execute:
+
+```bash
+bundle
+```
+
+Or install it yourself as:
+```bash
+gem install cpaas-ruby
+```
+
+In your application, you simply need to create a new initializer `config/initializers/cpaas.rb`.
+
+```ruby
+# Call the configure method
+Cpaas.configure do |config|
+  # Configuration
+end
+```
+
+After you've configured the SDK client, you can begin playing around with it to learn its functionality and see how it fits in your application. The API reference documentation will help to explain the details of the available features.
+
+## Configuration
+
+```ruby
+Cpaas.configure do |config|
+  config.client_id = '<private project key>'
+  config.client_secret = '<private project secret>'
+  config.base_url = '$KANDYFQDN$'
+end
+```
+
+The information required to be authenticated should be under:
+
++ `Projects` -> `{your project}` -> `Project info`/`Project secret`
+
+> + `Private Project key` should be mapped to `client_id`
+> + `Private Project secret` should be mapped to `client_secret`
+
+## Usage
+
+All modules can be accessed via the client instance. All method invocations follow the namespaced signature
+
+`{Client}::{ModuleName}.{method_name}(params)`
+
+Example:
+
+```ruby
+Cpaas::Conversation.create_message(params)
+```
+
+## Default Error Response
+
+### Format
+
+```ruby
+{
+  name: '<exception type>',
+  exception_id: '<exception id/code>',
+  message: '<exception message>'
+}
+```
+
+### Example
+
+```ruby
+{
+  name: 'serviceException',
+  exception_id: 'SVC0002',
+  message: 'Invalid input value for message part address'
+}
+```

data/tutorials/SMSMessaging.md

@@ -0,0 +1,132 @@
+# SMS Messaging
+In this section we will send an SMS to a mobile phone, then investigate how to receive incoming SMS messages.
+
+## Send SMS
+Let's assume that you want to send SMS to +16131234567 using +16139998877 as sender address, saying "hi :)":
+
+```ruby
+Cpaas::Conversation.create_message({
+  type: Cpaas::Conversation.types[:SMS],
+  destination_address: '+16131234567',
+  sender_address: '+16139998877',
+  message: 'hi :)'
+})
+```
+Before moving to how the response body looks, let's walk through the highlights on the SMS request:
+
++ `sender_address` indicates which DID number that user desires to send the SMS from. It is expected to be an E.164 formatted number.
+    + If `sender_address` field contains `default` keyword, $KANDY$ discovers the default assigned SMS DID number for that user and utilizes it as the sender address.
++ `destination_address` can either be an array of phone numbers or a single phone number string within the params containing the destinations that corresponding SMS message will be sent. For v1, only one destination is supported on $KANDY$.
++ Address value needs to contain a phone number, ideally in E.164 format. Some valid formats are:
+  - +16131234567
+  - 6131234567
+  - tel:+16131234567
+  - sip:+16131234567@domain
+  - sip:6131234567@domain
++ `message` field contains the text message in `UTF-8` encoded format.
+
+> The number provided in `sender_address` field should be an assigned/purchased number for the user, otherwise $KANDY$ replies back with a Forbidden error.
+
+Now, let's check the successful response:
+
+```ruby
+{
+  delivery_info: [{
+    destination_address: '+16131234567',
+    delivery_status: 'DeliveredToNetwork'
+  }],
+  message: 'hi :)',
+  sender_address: '+16139998877'
+}
+```
+In case of requesting `default` sender_address usage, sender_address field in response can be used to understand the actual number used since it contains the number being used as from address.
+
+> + The delivery_status can have the following values `DeliveredToNetwork`, `DeliveryImpossible`
+
+
+## Receive SMS
+To receive SMS, you need to:
+
++ have a SMS capable DID number assigned and configured on $KANDY$
++ subscribe to inbound SMS
+
+### Step 1: Subscription
+You subscribe to receive inbound SMS:
+
+```ruby
+Cpaas::Conversation.subscribe({
+  type: Cpaas::Conversation.types[:SMS],
+  webhook_url: 'https://myapp.com/inbound-sms/webhook',
+  destination_address: '+16139998877'
+})
+```
++ `destination_address` is an optional parameter to indicate which SMS DID number has been desired to receive SMS messages. Corresponding number should be one of the assigned/purchased numbers of the user or project/application, otherwise $KANDY$ replies back with Forbidden error. Also not providing this parameter triggers $KANDY$ to use the default assigned DID number against this user, in which case the response message for the subscription contains the `destination_address` field. It is highly recommended to provide `destination_address` parameter.
++ `webhook_url` is a webhook that is present in your application which is accessible from the public web. The sms notifications would be delivered to the webhook and the received notification can be consumed by using the `Cpaas::Notification.parse` helper method. The usage of `Cpaas::Notification.parse` is explained in Step 2.
+
+A successful subscription would return:
+```ruby
+{
+  webhook_url: 'https://myapp.com/inbound-sms/webhook',
+  destination_address: '+16139998877'
+  subscription_id: '544f12a3-123ad5e-b169'
+}
+```
+
+> + For every number required to receive incoming SMS, there should be an individual subscription.
+> + When a number has been unassigned from a user or project/application, all corresponding inbound SMS subscriptions are cancelled and `sms_subscription_cancellation_notification` notification is sent.
+
+Now, you are ready to receive inbound SMS messages via webhook, for example - 'https://myapp.com/inbound-sms/webhook'.
+
+### Step 2: Receiving notification
+An inbound SMS notification via webhook can be parsed by using the `Cpaas::Notification.parse` method:
+
+```ruby
+  def webhook(inbound_notification)
+    parsed_Response = Cpaas::Notification.parse(inbound_notification)
+  end
+```
+The parsed response returned from the `Cpaas::Notification.parse` method can look like this:
+```ruby
+{
+  date_time: 1568889113850,
+  destination_address: '+15202241139',
+  message: 'hi :)',
+  message_id: 'SM1-1568889114-1020821-00-66406cba',
+  sender_address: '+12066417772',
+  notification_id: '5ceb215a-163e-44f8-bbe2-d372d227ef44',
+  notification_date_time: 1568889114122,
+  type: 'inbound'
+}
+```
+
+## Real-time outbound SMS sync
+$KANDY$ provides notification for outbound SMS messages, to sync all online clients up-to-date in real time. The outbound notification received can also be parsed by using the `Cpaas::Notification.parse` method:
+
+```ruby
+  def webhook(outbound_notification)
+    parsed_response = Cpaas::Notification.parse(outbound_notification)
+  end
+```
+The parsed response returned from the `Cpaas::Notification.parse` method can look like this:
+
+```ruby
+{
+  date_time: 1569218381777,
+  destination_address: '+12533751556',
+  message: 'hi',
+  message_id: 'SM1-1569218382-1020821-10-d042a653',
+  sender_address: '+13162158074',
+  notification_id: 'fa1fd235-2042-4273-889e-904b0c6e58c5',
+  notification_date_time: 1569218381182,
+  type: 'outbound'
+}
+```
+With the help of this notification, clients can sync their view on sent SMS messages in real-time.
+
+> In order to receive this notification, user should have inbound SMS subscription. Obviously this notification cannot be provided when only send SMS has been used without an SMS related subscription.
+
+> For trial users, maximum number of SMS messages stored is 1000. When new messages are inserted to history, oldest ones are being removed.
+
+
+## References
+For all SMS related method details, refer to [SMS](/developer/references/ruby/1.0.0#sms-send).

data/tutorials/index.html

@@ -0,0 +1,86 @@
+<!DOCTYPE>
+<html>
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <title>Node.js SDK Tutorials</title>
+    <link rel="stylesheet" href="https://unpkg.com/docute@4/dist/docute.css">
+  </head>
+  <body>
+    <div id="docute"></div>
+    <script src="https://unpkg.com/docute@4/dist/docute.js"></script>
+    <script src="//cdn.jsdelivr.net/remarkable/1.7.1/remarkable.min.js"></script>
+    <script>
+      const sidebar = [{
+        title: "Tutorials",
+        links: [
+          {
+            title: 'Get Started',
+            link: 'GetStarted'
+          },
+          {
+            title: 'SMS Messaging',
+            link: 'SMSMessaging'
+          },
+          {
+            title: 'Two-Factor Authentication',
+            link: '2FA'
+          },
+        ]
+      }]
+      const queryParams = new URLSearchParams(window.location.search);
+      new Docute({
+        target: '#docute',
+        sidebar,
+        plugins: [
+          {
+            name: 'Hide Front Matter',
+            extend(api) {
+              api.processMarkdown(md => md.replace(/---([^]*?)---/m, ''))
+            }
+          },
+          {
+            name: 'Convert KANDYFQDN',
+            extend(api) {
+              const kandyFQDN = queryParams.get('KANDYFQDN') || '$KANDYFQDN$'
+              api.processMarkdown(md => md.replace(/\$KANDYFQDN\$/gm, kandyFQDN))
+            }
+          },
+          {
+            name: 'Convert KANDY',
+            extend(api) {
+              const kandy = queryParams.get('KANDY') || '$KANDY$'
+              api.processMarkdown(md => md.replace(/\$KANDY\$/gm, kandy))
+            }
+          },
+          {
+            // This is required so that docute/vue don't mangle
+            // the codepen form.
+            name: 'Unescape HTML',
+            extend(api) {
+              // This hook will wrap the html generated by the markdown
+              // in a div that uses vue's "v-html" directive so that the
+              // html is not escaped by Vue.
+              api.extendMarkdownComponent(component =>{
+                const rawHtml = String(component.template)
+                // Loop through every line of the markdown to find the codepen form
+                // and replace it with a div with the v-html directive and set the form
+                // as data for the view so that it gets rendered without being escaped.
+                const modifiedHtml = rawHtml.split('\n')
+                  .map(line => {
+                    if (line.startsWith('<form action="https://codepen.io/pen/define"')) {
+                      component.data = () => ({codepenForm: line})
+                      return '<div v-html="codepenForm"></div>'
+                    }
+                    return line
+                  })
+                  .join('\n')
+                component.template = modifiedHtml
+              })
+            }
+          }
+        ]
+      })
+    </script>
+  </body>
+</html>

data/tutorials/quickstarts.yml

@@ -0,0 +1,15 @@
+# "Display" data about quickstarts.
+# Information to be displayed on the Quickstarts page.
+
+- name: Get Started
+  description: This guide will get you started with $KANDY$ REST API Configuration, Authentication & Authorization, and Notification Channels.
+  link: /quickstarts/node/GetStarted
+
+- name: SMS Messaging
+  description: In this section we will send an SMS to a mobile phone, then investigate how to receive delivery receipts and incoming SMS messages.
+  link: /quickstarts/node/SMSMessaging
+
+- name: 2FA
+  description: $KANDY$ provides 2FA (two-factor authentication) API for developers to integrate their user authentication with other means, such as SMS.
+  link: /quickstarts/node/2FA
+

metadata

@@ -0,0 +1,238 @@
+--- !ruby/object:Gem::Specification
+name: cpaas-sdk
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Keepworks
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2019-11-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.6.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.6.2
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.20
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.20
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.2
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.2.1
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.17'
+description: SDK to build robust real-time communication applications.
+email:
+- kandy@keepworks.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.md
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- cpaas-sdk.gemspec
+- docs/Cpaas.html
+- docs/Cpaas/Conversation.html
+- docs/Cpaas/Notification.html
+- docs/Cpaas/TwoFactor.html
+- docs/_index.html
+- docs/_index.md
+- docs/class_list.html
+- docs/css/common.css
+- docs/css/full_list.css
+- docs/css/style.css
+- docs/file.README.html
+- docs/file._index.html
+- docs/file_list.html
+- docs/frames.html
+- docs/index.html
+- docs/js/app.js
+- docs/js/full_list.js
+- docs/js/jquery.js
+- docs/method_list.html
+- docs/mv_index.html
+- docs/top-level-namespace.html
+- examples/2fa/.env.example
+- examples/2fa/.gitignore
+- examples/2fa/.ruby-gemset
+- examples/2fa/.ruby-version
+- examples/2fa/Gemfile
+- examples/2fa/README.md
+- examples/2fa/app.rb
+- examples/2fa/config.ru
+- examples/2fa/helper.rb
+- examples/2fa/public/stylesheets/forms.css
+- examples/2fa/public/stylesheets/global.css
+- examples/2fa/public/stylesheets/layout.css
+- examples/2fa/public/stylesheets/main.css
+- examples/2fa/views/alert.erb
+- examples/2fa/views/dashboard.erb
+- examples/2fa/views/index.erb
+- examples/2fa/views/login.erb
+- examples/2fa/views/verify.erb
+- examples/sms/.env.example
+- examples/sms/.gitignore
+- examples/sms/.ruby-gemset
+- examples/sms/.ruby-version
+- examples/sms/Gemfile
+- examples/sms/README.md
+- examples/sms/app.rb
+- examples/sms/config.ru
+- examples/sms/helper.rb
+- examples/sms/public/scripts/notification.js
+- examples/sms/public/stylesheets/forms.css
+- examples/sms/public/stylesheets/global.css
+- examples/sms/public/stylesheets/layout.css
+- examples/sms/public/stylesheets/main.css
+- examples/sms/views/alert.erb
+- examples/sms/views/index.erb
+- lib/cpaas-sdk.rb
+- lib/cpaas-sdk/api.rb
+- lib/cpaas-sdk/config.rb
+- lib/cpaas-sdk/resources.rb
+- lib/cpaas-sdk/resources/conversation.rb
+- lib/cpaas-sdk/resources/notification.rb
+- lib/cpaas-sdk/resources/notification_channel.rb
+- lib/cpaas-sdk/resources/twofactor.rb
+- lib/cpaas-sdk/util.rb
+- lib/cpaas-sdk/version.rb
+- tutorials/2FA.md
+- tutorials/2fa-flow.png
+- tutorials/GetStarted.md
+- tutorials/SMSMessaging.md
+- tutorials/index.html
+- tutorials/quickstarts.yml
+homepage: https://github.com/Kandy-IO/kandy-cpaas-ruby-sdk
+licenses:
+- SEE LICENSE IN LICENSE.md
+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.7.3
+signing_key: 
+specification_version: 4
+summary: CPaaS Library
+test_files: []