opentok 3.0.3 → 4.1.1

data/lib/opentok/client.rb

@@ -12,18 +12,20 @@ module OpenTok
   class Client
     include HTTParty
 
-    open_timeout 2 # Set HTTParty default timeout (open/read) to 2 seconds
-
     # TODO: expose a setting for http debugging for developers
     # debug_output $stdout
 
-    def initialize(api_key, api_secret, api_url, ua_addendum="")
+    attr_accessor :api_key, :api_secret, :api_url, :ua_addendum, :timeout_length
+
+    def initialize(api_key, api_secret, api_url, ua_addendum='', opts={})
       self.class.base_uri api_url
       self.class.headers({
-        "User-Agent" => "OpenTok-Ruby-SDK/#{VERSION}" + "-Ruby-Version-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}" + (ua_addendum ? " #{ua_addendum}" : "")        
+        "User-Agent" => "OpenTok-Ruby-SDK/#{VERSION}" + "-Ruby-Version-#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}" + (ua_addendum ? " #{ua_addendum}" : "")
       })
       @api_key = api_key
       @api_secret = api_secret
+      @timeout_length = opts[:timeout_length] || 2
+      self.class.open_timeout @timeout_length
     end
 
     def generate_jwt(api_key, api_secret)
@@ -164,6 +166,72 @@ module OpenTok
       raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
 
+    def layout_archive(archive_id, opts)
+      opts.extend(HashExtensions)
+      response = self.class.put("/v2/project/#{@api_key}/archive/#{archive_id}/layout", {
+          :body => opts.camelize_keys!.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokArchiveError, "Setting the layout failed. The request was invalid or invalid layout options were given."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed. API Key: #{@api_key}"
+      when 500
+        raise OpenTokError, "Setting the layout failed. OpenTok server error."
+      else
+        raise OpenTokArchiveError, "Setting the layout failed."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def forceDisconnect(session_id, connection_id)
+      response = self.class.delete("/v2/project/#{@api_key}/session/#{session_id}/connection/#{connection_id}", {
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 204
+        response
+      when 400
+        raise ArgumentError, "Force disconnect failed. Connection ID #{connection_id} or Session ID #{session_id} is invalid"
+      when 403
+        raise OpenTokAuthenticationError, "You are not authorized to forceDisconnect, check your authentication credentials or token type is non-moderator"
+      when 404
+        raise OpenTokConnectionError, "The client specified by the connection ID: #{connection_id} is not connected to the session"
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def signal(session_id, connection_id, opts)
+      opts.extend(HashExtensions)
+      connectionPath = connection_id.to_s.empty? ? "" : "/connection/#{connection_id}"
+      url = "/v2/project/#{@api_key}/session/#{session_id}#{connectionPath}/signal"
+      response = self.class.post(url, {
+          :body => opts.camelize_keys!.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 204
+        response
+      when 400
+        raise ArgumentError, "One of the signal properties — data, type, sessionId or connectionId — is invalid."
+      when 403
+        raise OpenTokAuthenticationError, "You are not authorized to send the signal. Check your authentication credentials."
+      when 404
+        raise OpenTokError, "The client specified by the connectionId property is not connected to the session."
+      when 413
+        raise OpenTokError, "The type string exceeds the maximum length (128 bytes), or the data string exceeds the maximum size (8 kB)."
+      else
+        raise OpenTokError, "The signal could not be send."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
     def dial(session_id, token, sip_uri, opts)
       opts.extend(HashExtensions)
       body = { "sessionId" => session_id,
@@ -179,14 +247,151 @@ module OpenTok
       when 200
         response
       when 403
-        raise OpenTokAuthenticationError, "Authentication failed while dialing a sip session. API Key: #{@api_key}"
+        raise OpenTokAuthenticationError, "Authentication failed while dialing a SIP session. API Key: #{@api_key}"
       when 404
-        raise OpenTokSipError, "The sip session could not be dialed. The Session ID does not exist: #{session_id}"
+        raise OpenTokSipError, "The SIP session could not be dialed. The Session ID does not exist: #{session_id}"
+      else
+        raise OpenTokSipError, "The SIP session could not be dialed"
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def info_stream(session_id, stream_id)
+      streamId = stream_id.to_s.empty? ? '' : "/#{stream_id}"
+      url = "/v2/project/#{@api_key}/session/#{session_id}/stream#{streamId}"
+      response = self.class.get(url,
+                                headers: generate_headers('Content-Type' => 'application/json'))
+      case response.code
+      when 200
+        response
+      when 400
+        raise ArgumentError, 'Invalid request. You did not pass in a valid session ID or stream ID.'
+      when 403
+        raise OpenTokAuthenticationError, 'Check your authentication credentials. You passed in an invalid OpenTok API key.'
+      when 408
+        raise ArgumentError, 'You passed in an invalid stream ID.'
+      when 500
+        raise OpenTokError, 'OpenTok server error.'
       else
-        raise OpenTokSipError, "The sip session could not be dialed"
+        raise OpenTokError, 'Could not fetch the stream information.'
       end
     rescue StandardError => e
       raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
     end
+
+    def layout_streams(session_id, opts)
+      opts.extend(HashExtensions)
+      response = self.class.put("/v2/project/#{@api_key}/session/#{session_id}/stream", {
+          :body => opts.camelize_keys!.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokStreamLayoutError, "Setting the layout failed. The request was invalid or invalid layout options were given."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed. API Key: #{@api_key}"
+      when 500
+        raise OpenTokError, "Setting the layout failed. OpenTok server error."
+      else
+        raise OpenTokStreamLayoutError, "Setting the layout failed."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def start_broadcast(session_id, opts)
+      opts.extend(HashExtensions)
+      body = { :sessionId => session_id }.merge(opts.camelize_keys!)
+      response = self.class.post("/v2/project/#{@api_key}/broadcast", {
+          :body => body.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokBroadcastError, "The broadcast could not be started. The request was invalid or invalid layout options or exceeded the limit of five simultaneous RTMP streams."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while starting a broadcast. API Key: #{@api_key}"
+      when 409
+        raise OpenTokBroadcastError, "The broadcast has already been started for this session."
+      when 500
+        raise OpenTokError, "OpenTok server error."
+      else
+        raise OpenTokBroadcastError, "The broadcast could not be started"
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def get_broadcast(broadcast_id)
+      response = self.class.get("/v2/project/#{@api_key}/broadcast/#{broadcast_id}", {
+          :headers => generate_headers
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokBroadcastError, "The request was invalid."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while getting a broadcast. API Key: #{@api_key}"
+      when 404
+        raise OpenTokBroadcastError, "No matching broadcast found (with the specified ID)"
+      when 500
+        raise OpenTokError, "OpenTok server error."
+      else
+        raise OpenTokBroadcastError, "Could not fetch broadcast information."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def stop_broadcast(broadcast_id)
+      response = self.class.post("/v2/project/#{@api_key}/broadcast/#{broadcast_id}/stop", {
+          :headers => generate_headers
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokBroadcastError, "The request was invalid."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed while stopping a broadcast. API Key: #{@api_key}"
+      when 404
+        raise OpenTokBroadcastError, "No matching broadcast found (with the specified ID) or it is already stopped"
+      when 500
+        raise OpenTokError, "OpenTok server error."
+      else
+        raise OpenTokBroadcastError, "The broadcast could not be stopped."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
+    def layout_broadcast(broadcast_id, opts)
+      opts.extend(HashExtensions)
+      response = self.class.put("/v2/project/#{@api_key}/broadcast/#{broadcast_id}/layout", {
+          :body => opts.camelize_keys!.to_json,
+          :headers => generate_headers("Content-Type" => "application/json")
+      })
+      case response.code
+      when 200
+        response
+      when 400
+        raise OpenTokBroadcastError, "The layout operation could not be performed. The request was invalid or invalid layout options."
+      when 403
+        raise OpenTokAuthenticationError, "Authentication failed for broadcast layout. API Key: #{@api_key}"
+      when 500
+        raise OpenTokError, "OpenTok server error."
+      else
+        raise OpenTokBroadcastError, "The broadcast layout could not be performed."
+      end
+    rescue StandardError => e
+      raise OpenTokError, "Failed to connect to OpenTok. Response code: #{e.message}"
+    end
+
   end
 end

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/constants.rb

@@ -2,6 +2,6 @@ module OpenTok
   API_URL = "https://api.opentok.com"
   TOKEN_SENTINEL = "T1=="
   ROLES = { subscriber: "subscriber", publisher: "publisher", moderator: "moderator" }
-  ARCHIVE_MODES = Set.new([:manual, :always])
+  ARCHIVE_MODES = ::Set.new([:manual, :always])
   AUTH_EXPIRE = 300
 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
 
@@ -57,19 +69,21 @@ module OpenTok
     # @private
     # don't want these to be mutable, may cause bugs related to inconsistency since these values are
     # cached in objects that this can create
-    attr_reader :api_key, :api_secret, :api_url, :ua_addendum
+    attr_reader :api_key, :api_secret, :timeout_length, :api_url, :ua_addendum
 
     ##
     # 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.
+    # @option opts [Symbol] :timeout_length Custom timeout in seconds. If not provided, defaults to 2 seconds.
     def initialize(api_key, api_secret, opts={})
       @api_key = api_key.to_s()
       @api_secret = api_secret
+      @timeout_length = opts[:timeout_length] || 2
       @api_url = opts[:api_url] || API_URL
       @ua_addendum = opts[:ua_addendum]
     end
@@ -89,8 +103,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,14 +187,34 @@ 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
+      @client ||= Client.new api_key, api_secret, api_url, ua_addendum, timeout_length: @timeout_length
     end
 
   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