opentok 3.0.3 → 3.1.0

data/lib/opentok/connections.rb

@@ -0,0 +1,28 @@
+module OpenTok
+  #  A class for working with OpenTok connections.
+  class Connections
+    # @private
+    def initialize(client)
+      @client = client
+    end
+
+    # Force a client to disconnect from an OpenTok session.
+    #
+    # A client must be actively connected to the OpenTok session for you to disconnect it.
+    #
+    # @param [String] session_id The session ID of the OpenTok session.
+    # @param [String] connection_id The connection ID of the client in the session.
+    #
+    # @raise [ArgumentError] The connection_id or session_id is invalid.
+    # @raise [OpenTokAuthenticationError] You are not authorized to disconnect the connection. Check your authentication credentials.
+    # @raise [OpenTokConnectionError] The client specified by the connection_id  property is not connected to the session.
+    #
+    def forceDisconnect(session_id, connection_id )
+      raise ArgumentError, "session_id not provided" if session_id.to_s.empty?
+      raise ArgumentError, "connection_id not provided" if connection_id.to_s.empty?
+      response = @client.forceDisconnect(session_id, connection_id)
+      (200..300).include? response.code
+    end
+
+  end
+end

data/lib/opentok/exceptions.rb

@@ -8,5 +8,11 @@ module OpenTok
   class OpenTokSipError < OpenTokError; end
   # Defines errors raised when you attempt an operation using an invalid OpenTok API key or secret.
   class OpenTokAuthenticationError < OpenTokError; end
+  # Defines errors raised when you attempt a force disconnect a client and it is not connected to the session.
+  class OpenTokConnectionError < OpenTokError; end
+  # Defines errors raised when you attempt set layout classes to a stream.
+  class OpenTokStreamLayoutError < OpenTokError; end
+  # Defines errors raised when you perform Broadcast operations.
+  class OpenTokBroadcastError < OpenTokError; end
 
 end

data/lib/opentok/opentok.rb

@@ -2,17 +2,24 @@ require "opentok/constants"
 require "opentok/session"
 require "opentok/client"
 require "opentok/token_generator"
+require "opentok/connections"
 require "opentok/archives"
 require "opentok/sip"
+require "opentok/streams"
+require "opentok/signals"
+require "opentok/broadcasts"
 
 require "resolv"
 require "set"
 
 module OpenTok
-  # Contains methods for creating OpenTok sessions, generating tokens, and working with archives.
+  # Contains methods for creating OpenTok sessions and generating tokens. It also includes
+  # methods for returning object that let you work with archives, work with live streaming
+  # broadcasts, using SIP interconnect, sending signals to sessions, disconnecting clients from
+  # sessions, and setting the layout classes for streams.
   #
   # To create a new OpenTok object, call the OpenTok constructor with your OpenTok API key
-  # and the API secret from the OpenTok dashboard (https://dashboard.tokbox.com). Do not
+  # and the API secret for your {https://tokbox.com/account OpenTok project}. Do not
   # publicly share your API secret. You will use it with the OpenTok constructor (only on your web
   # server) to create OpenTok sessions.
   #
@@ -20,7 +27,7 @@ module OpenTok
   # @attr_reader [String] api_key @private The OpenTok API key.
   #
   #
-  # @!method generate_token(options)
+  # @!method generate_token(session_id, options)
   #   Generates a token for a given session.
   #
   #   @param [String] session_id The session ID of the session to be accessed by the client using
@@ -45,6 +52,11 @@ module OpenTok
   #     end-user. For example, you can pass the user ID, name, or other data describing the
   #     end-user. The length of the string is limited to 1000 characters. This data cannot be
   #     updated once it is set.
+  #   @option options [Array] :initial_layout_class_list
+  #     An array of class names (strings) to be used as the initial layout classes for streams
+  #     published by the client. Layout classes are used in customizing the layout of videos in
+  #     {https://tokbox.com/developer/guides/broadcast/live-streaming/ live streaming broadcasts}
+  #     and {https://tokbox.com/developer/guides/archiving/layout-control.html composed archives}.
   #   @return [String] The token string.
   class OpenTok
 
@@ -62,8 +74,8 @@ module OpenTok
     ##
     # Create a new OpenTok object.
     #
-    # @param [String] api_key Your OpenTok API key. See the OpenTok dashboard
-    #   (https://dashboard.tokbox.com).
+    # @param [String] api_key The OpenTok API key for your
+    #   {https://tokbox.com/account OpenTok project}.
     # @param [String] api_secret Your OpenTok API key.
     # @option opts [Symbol] :api_url Do not set this parameter. It is for internal use by TokBox.
     # @option opts [Symbol] :ua_addendum Do not set this parameter. It is for internal use by TokBox.
@@ -89,8 +101,8 @@ module OpenTok
     # Check the error message for details.
     #
     # You can also create a session using the OpenTok REST API (see
-    # http://www.tokbox.com/opentok/api/#session_id_production) or the OpenTok dashboard
-    # (see https://dashboard.tokbox.com/projects).
+    # http://www.tokbox.com/opentok/api/#session_id_production) or at your
+    # {https://tokbox.com/account OpenTok account page}.
     #
     # @param [Hash] opts (Optional) This hash defines options for the session.
     #
@@ -173,12 +185,32 @@ module OpenTok
       @archives ||= Archives.new client
     end
 
+    # A Broadcasts object, which lets you work with OpenTok live streaming broadcasts.
+    def broadcasts
+      @broadcasts ||= Broadcasts.new client
+    end
+
+    # A Sip object, which lets you use the OpenTok SIP gateway.
     def sip
       @sip ||= Sip.new client
     end
 
-    protected
+    # A Streams object, which lets you work with OpenTok live streaming broadcasts.
+    def streams
+      @streams ||= Streams.new client
+    end
 
+    # A Signals object, which lets you send signals to OpenTok sessions.
+    def signals
+      @signals ||= Signals.new client
+    end
+
+    # A Connections object, which lets disconnect clients from an OpenTok session.
+    def connections
+      @connections ||= Connections.new client
+    end
+
+    protected
     def client
       @client ||= Client.new api_key, api_secret, api_url, ua_addendum
     end

data/lib/opentok/session.rb

@@ -42,6 +42,11 @@ module OpenTok
   #     end-user. For example, you can pass the user ID, name, or other data describing the
   #     end-user. The length of the string is limited to 1000 characters. This data cannot be
   #     updated once it is set.
+  #   @option options [Array] :initial_layout_class_list
+  #     An array of class names (strings) to be used as the initial layout classes for streams
+  #     published by the client. Layout classes are used in customizing the layout of videos in
+  #     {https://tokbox.com/developer/guides/broadcast/live-streaming/ live streaming broadcasts}
+  #     and {https://tokbox.com/developer/guides/archiving/layout-control.html composed archives}.
   #   @return [String] The token string.
   class Session
 

data/lib/opentok/signals.rb

@@ -0,0 +1,47 @@
+module OpenTok
+  #  A class for working with OpenTok signals.
+  class Signals
+    # @private
+    def initialize(client)
+      @client = client
+    end
+
+    # Sends a signal to clients connected to an OpenTok session.
+    #
+    # You can send a signal to all valid connections in a session or to a specific connection of
+    # a session.
+    #
+    # For more information on signaling, see
+    # {https://tokbox.com/developer/rest/#send_signal}.
+    #
+    # @param [String] session_id The session ID of the OpenTok session.
+    #
+    # @param [String] connection_id
+    #   When a connection_id is specified, only that connection recieves the signal. 
+    #   Otherwise, the signal is sent to all clients connected to the session.
+    #
+    # @option options [String] :type This is the type of the signal. You can use this
+    # field to group and filter signals. It is a property of the Signal object received by
+    # the client(s).
+    #
+    # @option options [String] :data This is the data within the signal or the payload.
+    # Contains the main information to be sent in the signal. It is a property of the Signal object
+    # received by the client(s).
+    #
+    # @raise [ArgumentError]
+    #   One of the signal properties — data, type, session_id, or connection_id — is invalid.
+    # @raise [OpenTokAuthenticationError]
+    #   You are not authorized to send the signal. Check your authentication credentials.
+    # @raise [OpenTokError]
+    #   The client specified by the connection_id property is not connected to the session.
+    # @raise [OpenTokError]
+    #   The type string exceeds the maximum length (128 bytes), or the data string exceeds
+    #   the maximum size (8 kB).
+    def send(session_id, connectionId = "", options = {})
+      raise ArgumentError, "session_id not provided" if session_id.to_s.empty?
+      response = @client.signal(session_id, connectionId, options)
+      (200..300).include? response.code
+    end
+
+  end
+end

data/lib/opentok/sip.rb

@@ -1,7 +1,42 @@
 require "opentok/client"
 
+# An object that lets you use the OpenTok SIP gateway.
 module OpenTok
   class Sip
+    # Dials a SIP gateway to input an audio-only stream into your OpenTok session.
+    # See the {https://tokbox.com/developer/guides/sip/ OpenTok SIP developer guide}.
+    #
+    # @example
+    #    opts = { "from" => "14155550101@example.com",
+    #      "auth" => { "username" => sip_username,
+    #        "password" => sip_password },
+    #      "headers" => { "X-KEY1" => "value1",
+    #        "X-KEY1" => "value2" },
+    #      "secure" => "true"
+    #    }
+    #    response = opentok.sip.dial(session_id, token, "sip:+15128675309@acme.pstn.example.com;transport=tls", opts)
+    # @param [String] session_id The session ID corresponding to the session to which
+    #   the SIP gateway will connect.
+    # @param [String] token The token for the session ID with which the SIP user
+    #   will use to connect.
+    # @param [String] sip_uri The SIP URI the OpenTok SIP gateway will dial.
+    # @param [Hash] opts A hash defining options for the SIP call. For example:
+    # @option opts [String] :from The number or string that will be sent to the final
+    #   SIP number as the caller. It must be a string in the form of "from@example.com",
+    #   where from can be a string or a number. If from is set to a number
+    #   (for example, "14155550101@example.com"), it will show up as the incoming
+    #   number on PSTN phones. If from is undefined or set to a string (for example,
+    #   "joe@example.com"), +00000000 will show up as the incoming number on
+    #   PSTN phones.
+    # @option opts [Hash] :headers This hash defines custom headers to be added
+    #   to the SIP ​INVITE​ request initiated from OpenTok to the your SIP platform.
+    #   Each of the custom headers must start with the ​"X-"​ prefix, or the call
+    #   will result in a Bad Request (400) response.
+    # @option opts [Hash] :auth This object contains the username and password
+    #   to be used in the the SIP INVITE​ request for HTTP digest authentication,
+    #   if it is required by your SIP platform.
+    # @option opts  [true, false] :secure Wether the media must be transmitted
+    #   encrypted (​true​) or not (​false​, the default).
     def dial(session_id, token, sip_uri, opts)
       response = @client.dial(session_id, token, sip_uri, opts)
     end

data/lib/opentok/stream.rb

@@ -0,0 +1,46 @@
+require "active_support/inflector"
+
+module OpenTok
+  # Represents information about a stream in an OpenTok session.
+  #
+  # @attr [string] id
+  #   The stream ID.
+  #
+  # @attr [string] name
+  #   The name of the stream.
+
+  # @attr [string] videoType
+  #   The videoType property is either "camera" or "screen".
+  #
+  # @attr [array] layoutClassList
+  #   An array of the layout classes for the stream.
+  class Stream
+
+    # @private
+    def initialize(json)
+      # TODO: validate json fits schema
+      @json = json
+    end
+
+    # A JSON-encoded string representation of the stream.
+    def to_json
+      @json.to_json
+    end
+
+
+    # @private ignore
+    def method_missing(method, *args, &block)
+      camelized_method = method.to_s.camelize(:lower)
+      if @json.has_key? camelized_method and args.empty?
+        # TODO: convert create_time method call to a Time object
+        if camelized_method == 'outputMode'
+          @json[camelized_method].to_sym
+        else
+          @json[camelized_method]
+        end
+      else
+        super method, *args, &block
+      end
+    end
+  end
+end

data/lib/opentok/stream_list.rb

@@ -0,0 +1,18 @@
+require "opentok/stream"
+
+
+module OpenTok
+  # A class for accessing a list of Stream objects.
+  class StreamList < Array
+
+    # The total number streams.
+    attr_reader :total
+
+    # @private
+    def initialize(json)
+      @total = json['count']
+      super json['items'].map { |item| Stream.new item }
+    end
+
+  end
+end

data/lib/opentok/streams.rb

@@ -0,0 +1,79 @@
+require 'opentok/client'
+require 'opentok/stream'
+require 'opentok/stream_list'
+
+module OpenTok
+  # A class for working with OpenTok streams. It includes methods for getting info
+  # about OpenTok streams and for setting layout classes for streams.
+  class Streams
+    # @private
+    def initialize(client)
+      @client = client
+    end
+
+    # Use this method to get information on an OpenTok stream.
+    #
+    # For example, you can call this method to get information about layout classes used by an OpenTok stream.
+    # The layout classes define how the stream is displayed in the layout of a broadcast stream.
+    # For more information, see {https://tokbox.com/developer/guides/broadcast/live-streaming/#assign-layout-classes-to-streams Assigning layout classes to streams in live streaming broadcasts}
+    # and {https://tokbox.com/developer/guides/archiving/layout-control.html Customizing the video layout for composed archives}.
+    #
+    # @param [String] session_id The session ID of the OpenTok session.
+    # @param [String] stream_id The stream ID within the session.
+    # @return [Stream] The Stream object.
+    # @raise [ArgumentError] stream_id or session_id is invalid.
+    # @raise [OpenTokAuthenticationError] You are not authorized to fetch the stream information. Check your authentication credentials.
+    # @raise [OpenTokError] An OpenTok server error.
+    #
+    def find(session_id, stream_id)
+      raise ArgumentError, 'session_id not provided' if session_id.to_s.empty?
+      raise ArgumentError, 'stream_id not provided' if session_id.to_s.empty?
+      stream_json = @client.info_stream(session_id, stream_id)
+      Stream.new stream_json
+    end
+
+    # Use this method to get information on all OpenTok streams in a session.
+    #
+    # For example, you can call this method to get information about layout classes used by OpenTok streams.
+    # The layout classes define how the stream is displayed in the layout of a live streaming
+    # broadcast or a composed archive. For more information, see
+    # {https://tokbox.com/developer/guides/broadcast/live-streaming/#assign-layout-classes-to-streams Assigning layout classes to streams in live streaming broadcasts}
+    # and {https://tokbox.com/developer/guides/archiving/layout-control.html Customizing the video layout for composed archives}.
+    #
+    # @param [String] session_id The session ID of the OpenTok session.
+    # @return [StreamList] The StreamList of Stream objects.
+    # @raise [ArgumentError] The stream_id or session_id is invalid.
+    # @raise [OpenTokAuthenticationError] You are not authorized to fetch the stream information. Check your authentication credentials.
+    # @raise [OpenTokError] An OpenTok server error.
+    #
+    def all(session_id)
+      raise ArgumentError, 'session_id not provided' if session_id.to_s.empty?
+      response_json = @client.info_stream(session_id, '')
+      StreamList.new response_json
+    end
+
+    # Use this method to set the layout of a composed (archive or broadcast) OpenTok stream.
+    #
+    # For example, you can call this method to set the layout classes of an OpenTok stream.
+    # The layout classes define how the stream is displayed in the layout of a live streaming
+    # broadcast or a composed archive. For more information, see
+    # {https://tokbox.com/developer/guides/broadcast/live-streaming/#assign-layout-classes-to-streams Assigning layout classes to streams in live streaming broadcasts}
+    # and {https://tokbox.com/developer/guides/archiving/layout-control.html Customizing the video layout for composed archives}.
+    #
+    # @param [String] session_id The session ID of the OpenTok session.
+    # @param [Hash] opts  A hash with one key <code>items</code> and value as array of objects having <code>stream_id</code> and <code>layoutClassList</code> properties.
+    # For more information, see Layout{https://tokbox.com/developer/rest/#change-stream-layout-classes-composed}
+    # @raise [ArgumentError] The session_id is invalid.
+    # @raise [OpenTokAuthenticationError] You are not authorized to fetch the stream information. Check your authentication credentials.
+    # @raise [OpenTokStreamLayoutError] The layout operation could not be performed due to incorrect layout values.
+    # @raise [OpenTokError] An OpenTok server error.
+    #
+    def layout(session_id, opts)
+      raise ArgumentError, 'session_id not provided' if session_id.to_s.empty?
+      raise ArgumentError, 'opts is empty' if opts.empty?
+      response = @client.layout_streams(session_id, opts)
+      (200..300).include? response.code
+    end
+
+  end
+end

data/lib/opentok/version.rb

@@ -1,4 +1,4 @@
 module OpenTok
   # @private
-  VERSION = '3.0.3'
+  VERSION = '3.1.0'
 end

data/spec/cassettes/OpenTok_Archives/calls_layout_on_archive_object.yml

@@ -0,0 +1,45 @@
+---
+http_interactions:
+- request:
+    method: get
+    uri: https://api.opentok.com/v2/project/123456/archive/f6e7ee58-d6cf-4a59-896b-6d56b158ec71
+    body:
+      encoding: US-ASCII
+      string: ''
+    headers:
+      User-Agent:
+      - OpenTok-Ruby-SDK/<%= version %>
+      X-Opentok-Auth:
+      - eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImlzdCI6InByb2plY3QifQ.eyJpc3MiOiIxMjM0NTYiLCJpYXQiOjE0OTI1MTA2NjAsImV4cCI6MTQ5MjUxMDk2MH0.Oh_JHhtEUKK1pPV4s6neXJj_RXI8EcEpJRRpG_2c9U0
+  response:
+    status:
+      code: 200
+      message: OK
+    headers:
+      Server:
+      - nginx
+      Date:
+      - Wed, 26 Sep 2018 18:07:55 GMT
+      Content-Type:
+      - application/json
+      Connection:
+      - keep-alive
+    body:
+      encoding: UTF-8
+      string: |-
+        {
+          "createdAt" : 1395187836000,
+          "duration" : 62,
+          "id" : "f6e7ee58-d6cf-4a59-896b-6d56b158ec71",
+          "name" : "",
+          "partnerId" : 123456,
+          "reason" : "",
+          "sessionId" : "SESSIONID",
+          "size" : 8347554,
+          "status" : "available",
+          "url" : "http://tokbox.com.archive2.s3.amazonaws.com/123456%2Ff6e7ee58-d6cf-4a59-896b-6d56b158ec71%2Farchive.mp4?Expires=1395194362&AWSAccessKeyId=AKIAI6LQCPIXYVWCQV6Q&Signature=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+          "notarealproperty" : "not a real value"
+        }
+    http_version: 
+  recorded_at: Tue, 18 Apr 2017 10:17:40 GMT
+recorded_with: VCR 2.8.0