opentok 0.1.3 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0122202a607892b2550a526dc44c35b2beea87c8
-  data.tar.gz: b005eb0fba4ee0bdcec3123c87042936ff70673e
+  metadata.gz: 31559c8863e6d4d9fc421175f04ac721510500f7
+  data.tar.gz: 7c587bd56bec73b00a1b36250f42c3aefd2bc9a8
 SHA512:
-  metadata.gz: 7a15810ae54376c9442277c4cfd33ca3532378b5b0093a961cc6781734adf747f90771286fece4e428ecbcf143453152211f775ae1b99ef147031a7a4f5bec75
-  data.tar.gz: e85e3a3832c6984c7ec975e6acba8ff45669e8287f009fea12d7ec1ff77f6f0bc77c99f8bb12cbf4edd0438ebb985ebbb17629003028a02e44de1f39008150bf
+  metadata.gz: 18227e422d95dfa809324e6ebcd688768ac8fdfec9444039099ac853365492fdf4f362929508030ec7f6cb73d9e998fcd8cdc10836290edd7f5ce9e2ed74bed6
+  data.tar.gz: 3d1acb0a2cc1a03cfd8b1bf318c20c5dcca44e363df23cfe3882c2c52d2dfa662886b383c09b35b4fd1022ed99f37c4239751fe418d96e86e0a44751817ff866

data/.gitignore

@@ -1,5 +1,19 @@
 *.gem
+*.rbc
 .bundle
+.config
+.yardoc
 Gemfile.lock
-pkg/*
-.DS_Store
+InstalledFiles
+_yardoc
+coverage
+
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+.DS_Store

data/.travis.yml

@@ -0,0 +1,6 @@
+language: ruby
+rvm:
+  - "1.9.3"
+  - "2.0.0"
+  - "2.1.0"
+  - rbx-2

data/.yardopts

@@ -0,0 +1 @@
+'lib/**/*.rb' --no-private --readme doc/README.md

data/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing Guidelines
+
+For anyone looking to get involved to this project, we are glad to hear from you. Here are a few types of contributions
+that we would be interested in hearing about.
+
+*  Bug fixes
+    -  If you find a bug, please first report it using Github Issues.
+    -  Issues that have already been identified as a bug will be labelled `bug`.
+    -  If you'd like to submit a fix for a bug, send a Pull Request from your own fork and mention the Issue number.
+        +  Include a test that isolates the bug and verifies that it was fixed.
+*  New Features
+    -  If you'd like to accomplish something in the library that it doesn't already do, describe the problem in a new
+       Github Issue.
+    -  Issues that have been identified as a feature request will be labelled `enhancement`.
+    -  If you'd like to implement the new feature, please wait for feedback from the project maintainers before spending
+       too much time writing the code. In some cases, `enhancement`s may not align well with the project objectives at
+       the time.
+*  Tests, Documentation, Miscellaneous
+    -  If you think the test coverage could be improved, the documentation could be clearer, you've got an alternative
+       implementation of something that may have more advantages, or any other change we would still be glad hear about
+       it.
+       -  If its a trivial change, go ahead and send a Pull Request with the changes you have in mind
+       -  If not, open a Github Issue to discuss the idea first.
+
+## Requirements
+
+For a contribution to be accepted:
+
+*  The test suite must be complete and pass
+*  Code must follow existing styling conventions
+*  Commit messages must be descriptive. Related issues should be mentioned by number.
+
+If the contribution doesn't meet these criteria, a maintainer will discuss it with you on the Issue. You can still
+continue to add more commits to the branch you have sent the Pull Request from.
+
+## How To
+
+1. Fork this repository on GitHub.
+1. Clone/fetch your fork to your local development machine.
+1. Create a new branch (e.g. `issue-12`, `feat.add_foo`, etc) and check it out.
+1. Make your changes and commit them. (Did the tests pass?)
+1. Push your new branch to your fork. (e.g. `git push myname issue-12`)
+1. Open a Pull Request from your new branch to the original fork's `master` branch.
+
+## Developer Guidelines
+
+See DEVELOPING.md for guidelines for developing this project.

data/DEVELOPING.md

@@ -0,0 +1,91 @@
+# Development Guidelines
+
+This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain
+this project. If you use this package within your own software as is but don't plan on modifying it, this guide is
+**not** for you.
+
+## Tools
+
+*  [Bundler](http://bundler.io): used to ensure gems that are used as dependencies are uniform with other contributors
+   and maintainers. The first thing you should do once you've cloned this repository is to run `bundle install`. This
+   will also generate the `Gemfile.lock` file, which caches the configuration of gems you are using. Bundler is
+   included with all recent versions of Ruby.
+
+*  [Rake](http://rake.rubyforge.org/): used to run predefined tasks. Rake is usually run by prefixing `bundle exec` to
+   ensure that dependencies used for the task are provided through bundler. Example: `$ bundle exec rake spec`. Rake
+   is installed by Bundler when `bundler install` is run.
+
+## Tasks
+
+### Building
+
+Building is required to generate the gem. A gem is a distributable artifact suitable for installing on other systems.
+
+*  `rake build` - builds the gem into the `pkg` directory.
+
+### Testing
+
+This project's tests are written using [RSpec](http://rspec.info/). It also uses the VCR and WebMock helpers.
+
+*  `rake spec` - run the test suite.
+
+### Generating Documentation
+
+This project's reference documentation is generated by Yard and resides in the `docs` directory of the project.
+Common tasks:
+
+*  `rake yard` - generate the reference documentation.
+
+### Releasing
+
+In order to create a release, the following should be completed in order.
+
+1. Ensure all tests are passing (`rake spec`) and that there is enough test coverage.
+1. Make sure you are on the `master` branch of the repository, with all changes merged/committed already.
+1. Update the version number in the source code (`lib/opentok/version.rb`) and the README. See [Versioning](#versioning) for
+   information about selecting an appropriate version number.
+1. Commit the version number change with the message ("Update to version v.x.x.x"), substituting the new version number.
+1. Ensure you have permission to update the `opentok` gem on Rubygems: <https://rubygems.org/gems/opentok>.
+1. Run `rake release`, which will create a git tag for the version number, build, and push the gem to Rubygems.
+1. Change the version number for future development by adding ".alpha.1", then make another commit with the message
+   "Beginning development on next version".
+1. Push the changes to the main repository (`git push origin master`).
+
+## Workflow
+
+### Versioning
+
+The project uses [semantic versioning](http://semver.org/) as a policy for incrementing version numbers. For planned
+work that will go into a future version, there should be a Milestone created in the Github Issues named with the version
+number (e.g. "v2.2.1").
+
+During development the version number should end in ".alpha.1" or ".beta.x", where x is an increasing number starting
+from 1.
+
+### Branches
+
+*  `master` - the main development branch.
+*  `feat.foo` - feature branches. these are used for longer running tasks that cannot be accomplished in one commit.
+   once merged into master, these branches should be deleted.
+*  `vx.x.x` - if development for a future version/milestone has begun while master is working towards a sooner
+   release, this is the naming scheme for that branch. once merged into master, these branches should be deleted.
+
+### Tags
+
+*  `vx.x.x` - commits are tagged with a final version number during release.
+
+### Issues
+
+Issues are labelled to help track their progress within the pipeline.
+
+*  no label - these issues have not been triaged.
+*  `bug` - confirmed bug. aim to have a test case that reproduces the defect.
+*  `enhancement` - contains details/discussion of a new feature. it may not yet be approved or placed into a
+   release/milestone.
+*  `wontfix` - closed issues that were never addressed.
+*  `duplicate` - closed issue that is the same to another referenced issue.
+*  `question` - purely for discussion
+
+### Management
+
+When in doubt, find the maintainers and ask.

data/LICENSE

@@ -1,7 +1,21 @@
-Copyright (c) 2012 TokBox, Inc.
+The MIT License (MIT)
 
-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:
+Copyright (c) 2014 TokBox, Inc.
 
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-The software complies with Terms of Service for the OpenTok platform described in http://www.tokbox.com/termsofservice
-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.
+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

@@ -1,81 +1,198 @@
-# OpenTok Server SDK for Ruby
+# OpenTok Ruby SDK
 
-The OpenTok server SDK for Ruby lets you generate [sessions](http://tokbox.com/opentok/tutorials/create-session/) and
-[tokens](http://tokbox.com/opentok/tutorials/create-token/) for [OpenTok](http://www.tokbox.com/) applications.
+[![Build Status](https://travis-ci.org/opentok/Opentok-Ruby-SDK.png?branch=modernization)](https://travis-ci.org/opentok/Opentok-Ruby-SDK)
 
+The OpenTok Ruby SDK lets you generate
+[sessions](http://www.tokbox.com/opentok/tutorials/create-session/) and
+[tokens](http://www.tokbox.com/opentok/tutorials/create-token/) for
+[OpenTok](http://www.tokbox.com/) applications, and
+[archive](http://www.tokbox.com/platform/archiving) OpenTok 2.0 sessions.
 
-## Installation
+If you are updating from a previous version of this SDK, see
+[Important changes in v2.2](#important-changes-in-v22).
 
-To install using bundler, add Opentok to your `gemfile` and run `bundle install`:
-<pre>
-gem 'opentok'
-</pre>
+# Installation
 
-To install as a regular gem just type `gem install opentok`
+## Bundler (recommended):
 
+Bundler helps manage dependencies for Ruby projects. Find more info here: <http://bundler.io>
 
-## Requirements
+Add this gem to your `Gemfile`:
 
-The OpenTok server SDK for Ruby requires Ruby 1.9 or greater.
+```ruby
+gem "opentok", "~> 2.2.x"
+```
 
-You need an OpenTok API key and API secret, which you can obtain at <https://dashboard.tokbox.com>.
+Allow bundler to install the change.
+
+```
+$ bundle install
+```
+
+## RubyGems:
+
+```
+$ gem install opentok -v 2.2.0
+```
+
+# Usage
 
-# OpenTokSDK
+## Initializing
 
-In order to use any of the server side functions, you must first create an `OpenTokSDK` object with your developer credentials.  
-`OpenTokSDK` takes two parameters:
+Load the gem at the top of any file where it will be used. Then initialize an `OpenTok::OpenTok`
+object with your OpenTok API key and API secret.
 
-* key (string) - Given to you when you register  
-* secret (string) - Given to you when you register  
+```ruby
+require "opentok"
 
-<pre>
-# Creating an OpenTok Object
-API_KEY = ''     # replace with your OpenTok API key
-API_SECRET = ''  # replace with your OpenTok API secret
-OTSDK = OpenTok::OpenTokSDK.new API_KEY, API_SECRET
-</pre>
+opentok = OpenTok::OpenTok.new api_key, api_secret
+```
 
 ## Creating Sessions
-Call the `createSession()` method of the `OpenTokSDK` object to create a session. The method returns a Session object.
-The `sessionId` property of the Session object is the OpenTok session ID:
-<pre>
-# creating an OpenTok server-enabled session
-sessionId = OTSDK.createSession().to_s
 
-# Creating peer-to-peer session
-sessionProperties = {OpenTok::SessionPropertyConstants::P2P_PREFERENCE => "enabled"}
-sessionId = OTSDK.createSession( nil, sessionProperties ).to_s
-</pre>
+To create an OpenTok Session, use the `OpenTok.create_session(properties)` method. The
+`properties` parameter is an optional Hash used to specify whether you are creating a p2p Session
+and specifying a location hint. The `session_id` method of the returned `OpenTok::Session`
+instance is useful to get a sessionId that can be saved to a persistent store (e.g. database).
+
+```ruby
+# Just a plain Session:
+session = opentok.create_session
+
+# The session will attempt to transmit streams directly between clients.
+# If clients cannot connect, the session uses the OpenTok TURN server:
+session = opentok.create_session :media_mode => :relayed
+
+# A Session with a location hint:
+session = opentok.create_session :location => '12.34.56.78'
+
+# Store this sessionId in the database for later use:
+session_id = session.session_id
+```
 
 ## Generating Tokens
-With the generated session ID, you can generate tokens for each user:
 
-<pre>
-# Generating a publisher token
-token = OTSDK.generateToken :session_id => sessionId
- 
-# Generating a token with moderator role and connection data
-role = OpenTok::RoleConstants::MODERATOR
-connection_data = "username=Bob,level=4"
-token = OTSDK.generateToken :session_id => sessionId, :role => role, :connection_data => connection_data
-</pre>
+Once a Session is created, you can start generating Tokens for clients to use when connecting to it.
+You can generate a token either by calling the `opentok.generate_token(session_id, options)` method,
+or by calling the `session.generate_token(options)` method on the an instance after creating it. The
+`options` parameter is an optional Hash used to set the role, expire time, and connection data of
+the Token.
+
+```ruby
+# Generate a Token from just a session_id (fetched from a database)
+token = opentok.generate_token session_id
+
+# Generate a Token by calling the method on the Session (returned from createSession)
+token = session.generate_token
+
+# Set some options in a token
+token = session.generate_token({
+    :role        => :moderator
+    :expire_time => Time.now.to_i+(7 * 24 * 60 * 60) # in one week
+    :data        => 'name=Johnny'
+});
+```
+
+## Working with Archives
+
+You can start the recording of an OpenTok Session using the `opentok.archives.create(session_id,
+options)` method. This will return an `OpenTok::Archive` instance. The parameter `options` is an
+optional Hash used to assign a name for the Archive. Note that you can only start an
+Archive on a Session that has clients connected.
+
+```ruby
+archive = opentok.archives.create session_id :name => "Important Presentation"
+
+# Store this archive_id in the database for later use
+archive_id = archive.id
+```
+
+You can stop the recording of a started Archive using the `opentok.archives.stop_by_id(archive_id)`
+method. You can also do this using the `archive.stop` method of the `OpenTok::Archive` instance.
+
+```ruby
+# Stop an Archive from an archive_id (fetched from database)
+opentok.archives.stop_by_id archive_id
+# Stop an Archive from an instance (returned from opentok.archives.create)
+archive.stop
+```
+
+To get an `OpenTok::Archive` instance (and all the information about it) from an `archive_id`, use
+the `opentok.archives.find(archive_id)` method.
+
+```ruby
+archive = opentok.archives.find archive_id
+```
+
+To delete an Archive, you can call the `opentok.archives.delete_by_id(archive_id)` method or the
+`delete` method of an `OpenTok::Archive` instance.
+
+```ruby
+# Delete an Archive from an archive_id (fetched from database)
+opentok.archives.delete_by_id archive_id
+# Delete an Archive from an Archive instance (returned from archives.create, archives.find)
+archive.delete
+```
+
+You can also get a list of all the Archives you've created (up to 1000) with your API Key. This is
+done using the `opentok.archives.all(options)` method. The parameter `options` is an optional Hash
+used to specify an `:offset` and `:count` to help you paginate through the results. This will return
+an instance of the `OpenTok::ArchiveList` class.
+
+```ruby
+archive_list = opentok.archives.all
+
+# Get an specific Archive from the list
+archive_list[i]
+# Get the total number of Archives for this API Key
+$total = archive_list.total
+```
+
+# Samples
+
+There are two sample applications included in this repository. To get going as fast as possible, clone the whole
+repository and follow the Walkthroughs:
+
+*  [HelloWorld](sample/HelloWorld/README.md)
+*  [Archiving](sample/Archiving/README.md)
+
+# Documentation
+
+Reference documentation is available at <http://www.tokbox.com//opentok/libraries/server/ruby/reference/index.html> and in the
+doc directory of the SDK.
+
+# Requirements
+
+You need an OpenTok API key and API secret, which you can obtain at <https://dashboard.tokbox.com>.
+
+The OpenTok Ruby SDK requires Ruby 1.9.3 or greater.
+
+# Release Notes
+
+See the [Releases](https://github.com/opentok/opentok-ruby-sdk/releases) page for details
+about each release.
+
+## Important changes in v2.2
 
-Possible Errors:
+This version of the SDK includes support for working with OpenTok 2.0 archives. (This API does not
+work with OpenTok 1.0 archives.)
 
-* "Null or empty session ID are not valid"  
-* "An invalid session ID was passed"
+Note also that the `options` parameter of the `OpenTok.create_session()` method has a `media_mode`
+property instead of a `p2p` property.
 
-# Contributing
-To contribute, simple fork this repository and send a pull request when you are done.  
-Before you send pull requests, make sure all test cases are passing.  
+See the reference documentation
+<http://www.tokbox.com/opentok/libraries/server/ruby/reference/index.html> and in the
+docs directory of the SDK.
 
-To install necessary gems, type `bundle install` in the root directory.  
 
-To run test cases, type `rspec spec/` in the root directory.   
+# Development and Contributing
 
+Interested in contributing? We :heart: pull requests! See the [Development](DEVELOPING.md) and
+[Contribution](CONTRIBUTING.md) guidelines.
 
-# More information
+# Support
 
-See the [reference documentation](doc/reference.md).
+See <http://tokbox.com/opentok/support/> for all our support options.
 
-For more information on OpenTok, go to <http://www.tokbox.com/>.
+Find a bug? File it on the [Issues](https://github.com/opentok/opentok-ruby-sdk/issues) page. Hint:
+test cases are really helpful!